Mockingbird

Cloudflare Turnstile

@crvouga/mockingbird-service-turnstile

Deterministic Cloudflare Turnstile Siteverify token validation.

Parity: Siteverify JSON/form tokens, expiry and replayIdentity1 of 1 operationsIn-process fetchNode servermockingbird-turnstile
$
npm install -D @crvouga/mockingbird-service-turnstile
Source npm MarkdownAgent discoverySUPPORT.md

Playground

Requests go to the real emulator running in this tab. State persists across requests, and the journal shows what it received. A green dot marks operations whose sample succeeds as-is; others need ids from earlier responses.

Loads the real @crvouga/mockingbird-service-turnstile into this tab on first send
https://challenges.cloudflare.com

Send a request to see the emulator's response.

Operations

1 of 1 operations in the vendored contract are emulated.

MethodPathOperationStatus
POST/turnstile/v0/siteverifySiteverify

Documentation

The package README, the same file that ships in the npm tarball.Edit on GitHub

Local emulators. Real API contracts. Part of Mockingbird.

WIP Cloudflare Turnstile server-side Siteverify emulator. It never solves or issues real challenges.

Install

Shell
bun add @crvouga/mockingbird-service-turnstile

Usage

TypeScript
import { createServer } from "@crvouga/mockingbird-service-turnstile/server"

// Test setup: a local Siteverify, and a token like the one the widget hands the browser.
const server = await createServer()
const { token } = await server.runtime.instance().issue({
  hostname: "app.example.test", action: "signup",
}).json()

// Application code: the Siteverify call it makes to Cloudflare, sent to the emulator's URL.
const siteverifyUrl = `${server.url}/turnstile/v0/siteverify`
const result = await fetch(siteverifyUrl, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ secret: "mock_secret", response: token }),
})
console.log(await result.json()) // success, challenge_ts, hostname, action, cdata

await server.close()

Run mockingbird-turnstile serve --port 12126, then override the consumer's Siteverify URL with http://localhost:12126/turnstile/v0/siteverify. Keep the real Cloudflare origin in production. There is no universal consumer environment variable for this override. Send synthetic secret: mock_secret; configure additional sites with sites.

Contract

POST /turnstile/v0/siteverify accepts JSON or URL-encoded form fields secret, response, optional remoteip and UUID idempotency_key. Valid tokens return HTTP 200 and success: true with metadata. Rejection is HTTP 200 with success: false and error-codes, not a transport exception. Missing/invalid secrets, missing/invalid tokens, malformed bodies and expired/used tokens retain their documented error codes.

Tokens expire at five minutes on the emulator clock and are consumed once. Matching idempotency key retries replay the original response; other retries return timeout-or-duplicate. Wrong secrets do not consume a valid token. Applications must independently check the returned hostname/action. Remote IP is accepted, not used for actual bot detection.

Controls

  • POST /__admin/issue: issue a synthetic token; accepts siteKey (default mock_site), hostname, action, cdata. Defaults are for local testing only.
  • Constructor tokens and shared /__admin/state/tokens: seed token expiry/use state.
  • GET /__admin/attempts: metadata-only verification attempts, without secret/token bodies.
  • Shared clock, Timeline, reset, state, faults and request journal are available. Reset restores constructor sites/tokens; namespaces are isolated by header or /__admin/ns/{namespace}. Body secrets do not select namespaces. adminPrefix relocates the control tree.

Presets: internal_error (HTTP 200 verification rejection), rate_limited (scripted 429), server_error (503), connection_drop. Generic fault rules add deterministic latency. Transport presets are test controls, not claims about normal Siteverify status codes. No webhooks.

Tests use raw fetch (the requested client), JSON/form success, expiry boundary/replay, idempotency, malformed input, namespace/reset isolation, redacted journals and served HTTP timeouts/fail-closed behavior. Property tests validate Siteverify and detect divergence. bun scripts/parity.ts needs TURNSTILE_TEST_SECRET set to one of Cloudflare's documented public dummy keys; production keys are refused. It compares success/error envelopes in JSON and form modes, not production token issuance or private metadata.

Deliberately not modelled

Browser widget/script, bot detection, real challenges/tokens, multipart encoding, production token signing, IP reputation, hostname policy administration and enterprise metadata. Idempotency cache retention and conflicting/in-flight key policies are deterministic local stand-ins; only identical retry behavior is covered by the public contract evidence.

API

  • TurnstileAPI: FetchAPI with fetch, reset, issue, and site/token/attempt collections.
  • createRuntime: shared emulator contract plus token issuance/attempt inspection.
  • TURNSTILE_NAMESPACE: service name.
  • TURNSTILE_PRESETS: named failure controls.
  • document, operationIds, supportedOperationIds: generated OpenAPI metadata.
  • createServer, serveTarget, DEFAULT_PORT from ./server: Node HTTP/CLI serving, default port 12126.

Public types include Site, Token, TurnstileAPIOptions, OperationId and SupportedOperationId.

↑↓ to navigate↵ to open