Skip to content

Human Check

A bot check for your forms that asks visitors nothing. Their browser solves a small proof-of-work in the background, your server verifies the result, and nothing is stored on their device. It speaks Cloudflare Turnstile's API, so switching is a change of URLs and keys.

How it works

The widget loads in a small iframe served by HostStack. When the page renders it, the iframe asks for a challenge, solves it in Web Workers, and trades the solution for a token. The token lands in a hidden hs-human-check-response field in your form. Your server sends that token to siteverify with your secret and gets a yes or no.

  • The work is HashWX, a hash that runs a freshly generated program for every block of 65,536 attempts. A GPU solves it about 2× faster than a CPU — against about 150× for SHA-256 — so renting GPUs does not make a bot cheap. Each challenge is split into four sub-puzzles, solved in parallel, so the time is steady and there is a progress bar.
  • Tokens live 300 seconds and verify once. A second siteverify with the same token answers timeout-or-duplicate.
  • Nothing is stored on the device — no cookies, no local storage — and no fingerprint is kept. See Privacy.

Set it up

  1. Add a site

    Open Human Check in the dashboard and click Add site. Enter the hostnames your form runs on — each covers its subdomains, and localhost works for development. You get a public sitekey and a secret. The secret is shown once; HostStack keeps only a hash of it.

  2. Add the widget to your form

    signup.html
    <script src="https://hoststack.dev/api/human-check/v0/api.js" async defer></script>
    
    <form method="post" action="/signup">
      <!-- … your fields … -->
      <div class="hs-human-check" data-sitekey="hcs_..."></div>
      <button type="submit">Sign up</button>
    </form>
  3. Verify the token on your server

    Before acting on the form, POST the token to siteverify. Form-encoded and JSON bodies both work.

    const res = await fetch('https://hoststack.dev/api/human-check/v0/siteverify', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        secret: process.env.HUMAN_CHECK_SECRET,
        response: body['hs-human-check-response'],
        remoteip: clientIp, // optional
        idempotency_key: crypto.randomUUID(), // optional: makes a retry safe
      }),
    });
    const verdict = await res.json();
    if (!verdict.success) throw new Error('Human verification failed');

Hostnames and many domains

A site lists up to 20 hostnames by hand, and each one covers its subdomains. A platform whose customers each bring their own domain — a shop builder, a booking system — outgrows that list quickly. For those, link the HostStack service the domains are attached to. Every active domain on a linked service is an allowed hostname, with its subdomains. It needs no list entry and has no limit. A domain is allowed once it verifies, and stops being allowed within a minute of being removed. A site can link up to 10 services, and only services of its own team. In the dashboard, tick them under Linked services when you add or edit a site; from code, pass serviceIds.

ts
import { HostStack } from '@hoststack.dev/sdk';

const hs = new HostStack({ apiKey: process.env.HOSTSTACK_API_KEY });

// One site for every merchant: each active domain on service 145 is allowed.
const site = await hs.humanCheck.createSite(teamId, {
  name: 'Merchant checkouts',
  hostnames: ['shops.example.com'], // also covers every *.shops.example.com
  serviceIds: [145],
});

// One hostname at a time, idempotently — no read-modify-write of the list.
await hs.humanCheck.addHostname(teamId, site.id, 'staging.example.net');
await hs.humanCheck.removeHostname(teamId, site.id, 'staging.example.net');

hostnames and serviceIds on an update each replace their whole list. To change one hostname, use POST /api/human-check/:teamId/sites/:siteId/hostnames with { "hostname": "…" } and DELETE …/hostnames/:hostname. The same calls are available as addHostname / removeHostname in the SDK, hoststack human-check allow|disallow in the CLI, and add_human_check_hostname / remove_human_check_hostname in MCP. Both are idempotent. The 20-hostname limit applies to every team; linking a service is how you go past it.

When one sitekey serves many domains, also check the host on your server. siteverify returns the hostname the token was solved on.

js
const verdict = await verifyHumanCheck({ secret, response: token, remoteip });
// One sitekey serves many domains: make sure this token was solved on the
// host the checkout is running on, not on another merchant's.
if (!verdict.success || verdict.hostname !== req.hostname) refuse();

WordPress

The HostStack Human Check plugin protects WordPress without code: log in, registration and lost password on wp-login.php, comments, WooCommerce account forms and the classic checkout, and Contact Form 7. Each form can be switched off under Settings → Human Check.

  1. Install the plugin

    Download hoststack-human-check.zip and upload it under Plugins → Add New → Upload Plugin, or unzip it into wp-content/plugins/. Then activate it.

  2. Add your keys

    Paste the sitekey and secret under Settings → Human Check, or set them where they stay out of the database: the constants HOSTSTACK_HUMAN_CHECK_SITE_KEY and HOSTSTACK_HUMAN_CHECK_SECRET in wp-config.php, or the environment variables HUMAN_CHECK_SITE_KEY and HUMAN_CHECK_SECRET. Until both are set the plugin does nothing.

For your own forms, the plugin adds hoststack_human_check_widget() to print the widget, hoststack_human_check_verify() to check the posted token, and a [hoststack_human_check] shortcode. Not covered: the WooCommerce Checkout block, and logins over XML-RPC or the REST API.

Moving from Turnstile

A page built for Cloudflare Turnstile works unchanged once three things change — the script URL, the sitekey and secret, and the siteverify URL. Turnstile's names keep working, so you can migrate first and rename later, or never:

  • .cf-turnstile elements render automatically, and ?render=explicit and ?onload= work on the script URL.
  • window.turnstile is the same API as window.hoststackHumanCheck: render, execute, reset, remove, getResponse, isExpired, ready and implicitRender. A page that also loads Cloudflare's script keeps Cloudflare's window.turnstile.
  • A widget rendered the Turnstile way — a .cf-turnstile element or window.turnstile.render() — puts its token in cf-turnstile-response, so your server reads the field it always read.
  • siteverify takes the same fields and answers in the same shape, with the same error codes.
  • Cloudflare's test keys keep working — see Testing.

Widget options

Set them as data-* attributes, or pass them to hoststackHumanCheck.render(); camelCase names like cData and errorCallback are accepted too.

sitekey
stringrequired
The site's public key.
action
string
A label for this form, up to 32 of A–Z a–z 0–9 _ -. Returned by siteverify, so a login token cannot be spent on your signup form unnoticed.
cdata
string
Up to 255 of the same characters, returned by siteverify untouched.
callback, error-callback, expired-callback, timeout-callback
function
Called with the token, an error code, or nothing. Give a global function name in a data- attribute, or a function to render().
before-interactive-callback, after-interactive-callback, unsupported-callback
function
Around the click in managed mode, and for a browser that cannot run the check.
theme
"auto" | "light" | "dark"
Colours of the visible widget.

Default: auto

size
"normal" | "flexible" | "compact"
300×65, full width × 65, or 150×140 — Turnstile's sizes.

Default: normal

language
string
Twelve languages, picked from the browser by default.

Default: auto

execution
"render" | "execute"
execute waits for hoststackHumanCheck.execute() before solving.

Default: render

appearance
"always" | "execute" | "interaction-only"
When the visible widget is shown.

Default: always

response-field, response-field-name
boolean, string
Whether to add the hidden input, and its name. Widgets rendered the Turnstile way default to cf-turnstile-response.

Default: true, hs-human-check-response

retry, retry-interval
"auto" | "never", ms
Retrying after a failure that is not a configuration error.

Default: auto, 8000

refresh-expired
"auto" | "manual" | "never"
What happens when an unused token expires.

Default: auto

Explicit rendering

html
<script src="https://hoststack.dev/api/human-check/v0/api.js?render=explicit&onload=onHumanCheckReady" async defer></script>

<div id="check"></div>
<script>
  function onHumanCheckReady() {
    const id = hoststackHumanCheck.render('#check', {
      sitekey: 'hcs_...',
      action: 'signup',
      callback: (token) => console.log('verified', token),
      'error-callback': (code) => console.warn('check failed', code),
    });
    // hoststackHumanCheck.getResponse(id), .reset(id), .remove(id)
  }
</script>

Check on submit

js
hoststackHumanCheck.render('#check', { sitekey: 'hcs_...', execution: 'execute' });

form.addEventListener('submit', (e) => {
  if (!hoststackHumanCheck.getResponse('#check')) {
    e.preventDefault();
    hoststackHumanCheck.execute('#check'); // starts the check now; callback fires when done
  }
});

Content Security Policy

The solver, its WebAssembly and its requests all run inside HostStack's frame, under HostStack's own policy. Your page only needs to allow the script and the frame:

Content-Security-Policy:
  script-src 'self' https://hoststack.dev;
  frame-src  https://hoststack.dev;

Modes and difficulty

ModeWhat the visitor sees
invisibleNothing. The check runs while they fill in the form. The default.
non-interactiveA small status box that verifies by itself.
managedThe status box — and, for a visitor who looks risky, one click before the check starts.

Difficulty sets the base cost of a solve, as expected HashWX evaluations: low 250,000, normal 500,000, high 1,000,000. On a typical phone, normal takes about a second, usually while the visitor is still typing.

Escalation

The price goes up for visitors that look like automation:

  • Asking often — more than 8 challenges a minute from one address (an IPv4 address or an IPv6 /64) doubles it, more than 20 quadruples it, more than 50 makes it eight times. Busy networks (/24 or /48) add more.
  • Where it comes from — datacenter addresses pay 4×, VPNs 2×. iCloud Private Relay and WARP are flagged but not charged, because ordinary people use them.
  • What it is — an HTTP library instead of a browser pays 4×, a headless or automated browser 2×, and signals the browser reports about itself (webdriver, software rendering and similar) up to 4×.

All of it together is capped at 16×. Past 120 challenges a minute from one address the widget gets 429 rate-limited instead of a puzzle.

Verifying tokens

POST https://hoststack.dev/api/human-check/v0/siteverify, form-encoded or JSON. It always answers 200; read success.

secret
stringrequired
The site's secret (hcsec_…).
response
stringrequired
The token from hs-human-check-response (or cf-turnstile-response on a page migrated from Turnstile).
remoteip
string
The visitor's address. Used only to answer metadata.ip_match.
idempotency_key
UUID
Send the same key on a retry and you get the first answer back instead of timeout-or-duplicate.
200 OK
{
  "success": true,
  "error-codes": [],
  "challenge_ts": "2026-11-10T14:03:11.000Z",
  "hostname": "shop.example.com",
  "action": "signup",
  "cdata": "",
  "metadata": {
    "risk_flags": ["ip_vpn"],
    "difficulty_multiplier": 2,
    "solve_ms": 1840,
    "ip_match": true
  }
}

metadata is ours, on top of Turnstile's fields: risk_flags (why the check was harder, or what looked odd), difficulty_multiplier, solve_ms, and ip_match — whether remoteip is on the network the token was solved from. They are signals: success already means the work was done. Use them to add your own friction, such as an email confirmation, for a risky-looking signup.

Error codeMeaning
missing-input-secretNo secret was sent.
invalid-input-secretThe secret is wrong, or was rotated more than 24 hours ago.
missing-input-responseNo token was sent.
invalid-input-responseNot a token, or a token for a different site.
bad-requestThe request could not be read.
timeout-or-duplicateThe token is older than 300 seconds, or was already verified.
internal-errorHostStack could not check single use. Retry with the same idempotency_key.

Testing

Cloudflare's published test keys behave as they do on Turnstile, so CI written for Turnstile keeps passing. The test sitekeys produce the dummy token XXXX.DUMMY.TOKEN.XXXX, which only the test secrets accept.

KeyBehaviour
1x00000000000000000000AASitekey: always passes (visible)
2x00000000000000000000ABSitekey: always fails (visible)
1x00000000000000000000BBSitekey: always passes (invisible)
2x00000000000000000000BBSitekey: always fails (invisible)
3x00000000000000000000FFSitekey: asks for a click, then passes
1x0000000000000000000000000000000AASecret: always passes
2x0000000000000000000000000000000AASecret: always fails
3x0000000000000000000000000000000AASecret: answers timeout-or-duplicate

Keys and rotation

The sitekey is public. The secret is shown once, when you create the site or rotate it. A rotation gives you a new secret at once, and the old one keeps verifying for 24 hours so you can deploy without refusing anyone. Deleting a site stops its tokens verifying immediately.

What it does not do

  • It prices bots; it does not stop them outright. A determined attacker can pay the work, and humans paid to solve checks get through any captcha. Keep your own rate limits and email verification behind it.
  • Browser signals can be faked. They only make a solve dearer and are reported in risk_flags; nothing is refused on them alone.
  • No WebAssembly — Apple's Lockdown Mode turns it off — gets a SHA-256 puzzle at twice the work instead, flagged no_wasm.

Privacy

The widget sets no cookies and writes nothing to the device. The visitor's IP address is used for per-minute rate counters that expire after two minutes, and inside the token as a keyed tag of their network (not the address) so siteverify can answer ip_match. Browser signals are sent with the challenge request and kept only as flags inside that token. There is no image puzzle, so it meets WCAG 2.2's no-cognitive-test rule; status changes are announced to screen readers.

Next steps

Was this page helpful?