@crvouga/mockingbird-service-turnstile

Local emulators. Real API contracts. Part of Mockingbird.

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

Install

bun add @crvouga/mockingbird-service-turnstile

Usage

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.