Developing Capybara

After validating the idea of a privacy-first CAPTCHA, the next challenge was execution.
This meant translating the Proof of Work concept into a real, production-ready system that could scale globally without traditional servers.

Design Goals

I set out with three non-negotiable technical goals:

Architecture

The system combines three core pieces:

• Cloudflare Worker → Acts as the API layer (/api/challenge, /api/verify, etc.)
• KV Namespace CAPY_KV → Stores per-IP rate limits and active challenges
• Proof of Work Logic → Generates nonce-based SHA-256 challenges & validates solutions

Quick Start

You can deploy instantly to Cloudflare Workers by clicking the button below.
This method automatically configures the required KV namespace and deployment settings.

Local Setup

0. Wrangler Prepare

wrangler kv namespace create "CAPY_KV"
wrangler kv namespace create "CAPY_KV --preview"

1. Create Project Directory

mkdir capybara
cd capybara

2. Copy Templates

• worker.js (single-file Worker, standalone mode)
• wrangler.jsonc (fill in your KV id/preview_id)

3. Configure wrangler.jsonc

• REDIRECT_URL: redirect target for /
• Limits: DEFAULT_DIFFICULTY, MIN_DIFFICULTY, MAX_DIFFICULTY, DEFAULT_DURATION_SEC, MIN_DURATION_SEC, MAX_DURATION_SEC, LIMIT_MAX_CHALLENGES_PER_DAY
• Namespacing: KV_PREFIX_BASE, INSTANCE_ID

4. Run Locally

wrangler dev --local --port 8789 --config wrangler.jsonc | cat

5. Deploy

wrangler deploy --config wrangler.jsonc

6. Confirm Public URL

Example: https://capybara.yourname.workers.dev

7. Using Captcha

Once deployed, you can start testing and using the provided Captcha components:

HTML Demo

• Download Demo.html

TypeScript Component

• Download captcha.tsx

These components can be integrated directly into your front-end projects to use Capybara CAPTCHA effortlessly.

Implementation Highlights

• Per-IP Limits: Lightweight abuse prevention via KV counters
• Configurable Difficulty: Adjustable challenge hardness
• Ephemeral Storage: Challenges expire after duration, ensuring no long-term persistence
• Namespacing: Supports multi-instance deployments with INSTANCE_ID

API Shape

Capybara mimics the familiar shape of CAPTCHA APIs to make integration painless:

1
// Challenge generation
2
POST /api/challenge
3
→ ( id, nonce, difficulty, duration )
4

5
// Challenge retrieval
6
GET /api/challenge/:id
7
→ ( nonce, difficulty, duration )
8

9
// Solution verification
10
POST /api/verify
11
→ ( id, solution )
12
→ ( success: boolean )

Each challenge is namespaced by KV_PREFIX_BASE:INSTANCE_ID so multiple deployments can coexist without collision.

Challenge Lifecycle

1. Client requests POST `/api/challenge`
   → Worker checks per-IP limits in KV
   → Worker generates nonce, assigns difficulty/duration
   → Challenge is stored in KV
   → Response sent back with (id, nonce, difficulty, duration)

2. Client later submits POST /api/verify (id, solution)
   → Worker fetches challenge by id from KV
   → Proof of Work is verified against SHA-256 target
   → Returns ( success: true/false )

KV Structure

1
# IP-based limit tracking
2
Key: `KV_PREFIX_BASE`:`INSTANCE_ID`:IP:(ip_address)
3
Value:
4
  challengesToday: number
5
  lastChallengeTs: timestamp
6

7
# Challenge storage
8
Key: `KV_PREFIX_BASE`:`INSTANCE_ID`:CH:(challenge_id)
9
Value:
10
  nonce: string
11
  difficulty: number
12
  duration: number
13
  createdAt: timestamp

This lightweight KV schema allows both rate-limiting and challenge validation without any external database.

Outcome

The development approach proved effective:

• Fast: ~50ms average Worker response time
• Efficient: ~5KB storage per challenge
• Scalable: 100k daily requests within Cloudflare free tier

Related Posts

Conclusion

Developing Capybara reinforced the power of serverless platforms for building privacy-respecting security tools. What started as a minimal prototype became a reliable, open-source CAPTCHA alternative—demonstrating how simple KV-backed architectures can solve real security problems without complexity or cost.