Rate Limiting & Bot Protection

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib/rate-limit.ts
• src/app.ts
• scripts/setup-cf.js
• wrangler.toml
• src/routes/mcp.ts
• README.md

e-zer0 implements a multi-layered security strategy to protect the system from brute-force attacks, automated bots, and unauthorized access. This system relies on Cloudflare KV for request throttling and Cloudflare Turnstile for challenge-response bot detection.

The protection suite covers sensitive endpoints including the administrative login, the Model Context Protocol (MCP) token exchange, and the initial setup wizard. By leveraging Cloudflare's edge infrastructure, these protections operate before malicious traffic consumes significant compute resources.

Rate Limiting Architecture

The rate limiting system uses Cloudflare KV as a distributed state store to track request attempts across multiple Worker isolates. The logic follows a "fail-closed" pattern; if the KV namespace is not correctly bound, the system denies access to sensitive operations to prevent bypasses.

The diagram above illustrates the request validation flow using Cloudflare KV.
Sources: src/lib/rate-limit.ts:1-35, src/app.ts:31-37

Key Components

Component	Function	File Path
checkRateLimit	Validates if the current key has exceeded its attempt threshold.	src/lib/rate-limit.ts
incrementRateLimit	Increases the failure count in KV with a specific TTL (default 900s).	src/lib/rate-limit.ts
clearRateLimit	Removes the attempt record from KV upon successful authentication.	src/lib/rate-limit.ts
RATE_LIMITER	The KV Namespace binding required for state storage.	wrangler.toml

Endpoint Protections

MCP Token Exchange

The /mcp/token endpoint enforces rate limits based on a combination of the client's IP address and the client_id. This prevents targeted brute-forcing of specific agent credentials.

1. Refresh Token Pre-check: Before validating JWT signatures, the system checks if the IP has failed too many refresh attempts.
2. Client-ID Throttling: Once a client_id is identified, attempts are tracked against rate_limit:mcp:${ip}:${clientId}.
3. Automatic Lockout: Exceeding 5 attempts results in a 15-minute lockout period.

Sources: src/routes/mcp.ts:153-157, src/routes/mcp.ts:184-187

OAuth Dynamic Registration

To prevent resource exhaustion through spam client registration, the system applies two distinct limits:

• Burst Limit: Limits the number of registrations per IP within a short window.
• Daily Cap: Enforces a maximum number of registrations per day, even if burst windows are cleared.

Sources: src/routes/mcp-auth.test.ts:983-1025

Bot Protection (Cloudflare Turnstile)

e-zer0 integrates Cloudflare Turnstile to verify that interactions with the setup and login pages are performed by humans. This protection is automatically provisioned during deployment.

Automated Provisioning

The setup-cf.js script manages the Turnstile lifecycle:

1. It checks for an existing Turnstile widget named after the INSTANCE_NAME.
2. If missing, it creates a new "managed" mode widget via the Cloudflare API.
3. It pushes the TURNSTILE_SITE_KEY and TURNSTILE_SECRET_KEY as Worker secrets.

Sources: scripts/setup-cf.js:187-236

UI Integration

The bot challenge is rendered in the login and setup views using the Cloudflare client-side library. The Layout component conditionally includes the Turnstile script when a site key is provided.

This sequence shows the interaction between the user, the worker, and the Turnstile service.
Sources: src/views/layout.tsx:24-25, README.md:154-160

Security Configuration

The application requires specific environment bindings to enable these protections.

# wrangler.toml
[[kv_namespaces]]
binding = "RATE_LIMITER"
id = "local" # Replaced with actual ID in production

Protection Summary

• Brute Force Protection: Enforced via checkRateLimit on /login and /mcp/token.
• CSRF Protection: The csrf() middleware protects mutation routes (/settings/*, /agents/*, /accounts/*, /setup/*).
• Secure Headers: The secureHeaders() middleware is applied globally to all requests.
• Index Prevention: A global robots.txt route disallows all search engine indexing.

Sources: src/app.ts:40-47, src/app.ts:117-119, wrangler.toml:25-29

Conclusion

Rate limiting and bot protection in e-zer0 provide a robust defense against automated threats. By combining Cloudflare KV-based throttling for API endpoints and Turnstile challenges for the web UI, the system ensures that only authorized humans and agents can interact with sensitive email data.