Geo-Block Worker

Geo-Block Worker

A production-ready Cloudflare Worker that enforces country-level access control at the edge — before requests ever reach your origin. Configure allow-lists or deny-lists via Cloudflare KV, so rule changes take effect instantly without a deployment.

What You Get

• A fully commented src/index.js worker with allow-list and deny-list modes
• wrangler.toml pre-wired with KV namespace bindings
• Configurable redirect URL or 403 response on block
• Bypass header support (X-Geo-Bypass) for internal traffic and health checks
• .env.example and setup guide in the README

How It Works

The worker reads the visitor country from cf.country on every request (no external lookups, zero latency overhead). It checks the country code against a KV-stored list. In deny mode the worker blocks listed countries with a 403 or redirect. In allow mode it blocks everyone except listed countries. Mode and the country list are both stored in KV — update them in the Cloudflare dashboard or via the Wrangler CLI with no redeployment needed.

Developer Experience

• Deploy in under 5 minutes: wrangler deploy
• Test locally with wrangler dev and a spoofed CF-IPCountry header
• Seed initial KV values with the included helper script
• Works with any Cloudflare zone — add as a route or use Workers Routes

Requirements

• Cloudflare account (free tier works)
• Wrangler CLI v3+ (npm install -g wrangler)
• One KV namespace (created automatically by the setup script)