A Cloudflare Worker that adds BotShield anonymous human verification to any website. Deploy it on your own Cloudflare account — no PII collected, no tracking.
Visitor → your domain → Cloudflare Worker (this repo)
│
┌─────────┴──────────┐
│ │
Valid session? No session
│ │
Proxy to origin Show verification page
│
User verifies in BotShield app
│
Callback sets session cookie
│
Proxy to origin ✓
- Visitor hits your domain — the Worker checks for a
botshield_sessioncookie. - No valid session — redirects to
/gate(a verification page). - User taps "Verify Presence" — opens the BotShield app for a biometric check.
- On success, BotShield redirects back to
/gate/callbackwith a signed JWT. - Worker validates the JWT, sets an HttpOnly cookie, and proxies to your origin.
npm installnpx wrangler kv namespace create GATE_CACHECopy the returned id into wrangler.toml.
Edit wrangler.toml:
[vars]
ORIGIN_HOST = "origin.mystore.com" # Your real server
GATE_ID = "gate_abc123" # From BotShield dashboardSet your JWT secret:
npx wrangler secret put BOTSHIELD_JWT_SECRET
# Paste the HS256 key from your BotShield dashboardnpm run deployAdd a DNS record in Cloudflare pointing your domain to this Worker (custom domain or route), or use the workers.dev subdomain for testing.
See examples/path-allowlist.ts — import it in worker/index.ts to bypass the gate for API routes, static assets, health checks, etc.
See examples/custom-branding.ts — copy it to worker/gateHtml.ts and customize the HTML/CSS to match your brand. The only requirement is that the verification link points to the BotShield verify URL.
| Variable | Type | Description |
|---|---|---|
BOTSHIELD_JWT_SECRET |
Secret | HS256 signing key from BotShield dashboard |
BOTSHIELD_API_URL |
Var | BotShield API base (default: https://api.botshield.ai) |
BOTSHIELD_API_KEY |
Var/Secret | Your BotShield API key |
ORIGIN_HOST |
Var | Your origin server hostname |
GATE_ID |
Var | Gate ID from BotShield dashboard |
GATE_CACHE |
KV Binding | KV namespace for config caching |
- No PII — BotShield never stores personal data. The gate only validates presence.
- HttpOnly cookies — session tokens can't be read by client-side JavaScript.
- HS256 JWT — tokens are signed and validated using Web Crypto API (no Node.js deps).
- Header sanitization — Cloudflare headers and the gate cookie are stripped before proxying.
MIT