Cloudflare Deployment Configuration

Relevant source files

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

• wrangler.toml
• scripts/setup-cf.js
• README.md
• src/app.ts
• src/types.ts
• AGENTS.md

e-zer0 operates as a self-hosted bridge between AI agents and email providers, built exclusively on the Cloudflare Developer Platform. The deployment configuration leverages Cloudflare Workers for compute, D1 for relational storage, Vectorize for semantic search, and KV for rate limiting. The system uses a "Zero-Config" philosophy where resource provisioning and secret generation are automated via specialized scripts and GitHub Actions.

The architecture ensures that all sensitive data, including email content and credentials, remains within your own Cloudflare infrastructure. This deployment model supports both a free tier for light personal use and a paid tier for high-volume processing by autonomous agents.
Sources: README.md:14-25, AGENTS.md:14-22

Architecture Overview

The e-zer0 system utilizes several Cloudflare-native components to handle different aspects of the application lifecycle.

Component Map

Component	Cloudflare Technology	Purpose
Compute	Cloudflare Workers	Runs the TypeScript/Hono application logic at the edge.
Database	Cloudflare D1	Stores admin users, email account metadata, and audit logs.
Vector Search	Vectorize & Workers AI	Stores email embeddings and performs semantic searches.
Rate Limiting	Workers KV	Provides brute-force protection for sensitive endpoints.
Security	Cloudflare Turnstile	Protects setup and login routes from automated bot attacks.
Secrets	Workers Secrets	Stores encryption keys and JWT secrets securely.

Sources: AGENTS.md:14-22, wrangler.toml:1-40, README.md:104-118

The following diagram illustrates the relationship between these Cloudflare services and the e-zer0 application:

Provisioning and Setup

Resource provisioning is handled by the scripts/setup-cf.js script. This script performs both local environment preparation and remote Cloudflare resource creation.

Resource Provisioning Workflow

1. Local Key Generation: The script checks .dev.vars. If ENCRYPTION_KEY or JWT_SECRET are missing or contain placeholders, it generates new 64-character hexadecimal secrets.
2. Authentication Check: The script runs wrangler whoami. If unauthenticated, it skips remote provisioning.
3. D1 Creation: Creates a database named ${INSTANCE_NAME}-db and retrieves its UUID.
4. Vectorize Creation: Creates an index named ${INSTANCE_NAME}-index with 384 dimensions and cosine metric.
5. KV Namespace: Creates a namespace bound as RATE_LIMITER.
6. Config Generation: Dynamically writes the wrangler.toml file with the newly created resource IDs.
7. Secret Injection: Pushes local encryption keys and Turnstile keys to Cloudflare's secret store.

Sources: scripts/setup-cf.js:19-148

Worker Configuration (wrangler.toml)

The wrangler.toml file defines the environment bindings that the application uses at runtime. These bindings are accessed in the code via the c.env object in Hono or the Env interface.

Environment Bindings

• D1 Database: Bound to DB. It points to e-zer0-db and specifies the migrations directory for schema updates.
• Vectorize: Bound to VECTOR_INDEX.
• AI: Bound to AI for generating embeddings.
• KV: Bound to RATE_LIMITER.
• Compatibility: Set to 2026-03-01 with the nodejs_compat flag enabled.
• Cron Triggers: Configured to run every 30 minutes (*/30 * * * *) for background tasks like token refresh.

Sources: wrangler.toml:1-43, src/types.ts:4-21

Startup Protection

The application includes a startup guard that validates critical bindings. If the RATE_LIMITER KV namespace is not bound, the worker returns a 503 Service Misconfigured error to prevent insecure operations on sensitive routes.
Sources: src/app.ts:36-43

Deployment via GitHub Actions

e-zer0 supports automated deployment through GitHub Actions, requiring only two repository secrets:

1. CLOUDFLARE_API_TOKEN: Requires permissions for D1, Vectorize, KV, Workers Scripts, Secrets, and Turnstile.
2. CLOUDFLARE_ACCOUNT_ID: Found in the Cloudflare dashboard.

The INSTANCE_NAME variable defines the prefix for all created resources (e.g., my-app-db). The workflow automatically provisions the database, sets up the vector index, generates encryption keys, and deploys the UI.
Sources: README.md:129-160

Security Configuration

Secret Management

Secrets are not stored in the D1 database as plain text. OAuth credentials and provider tokens are encrypted at rest using AES-256-GCM. The ENCRYPTION_KEY used for this process is stored as a Cloudflare Worker Secret, ensuring it is never exposed in logs or source code.
Sources: AGENTS.md:54-60, README.md:58-61

Bot Protection (Turnstile)

The deployment script automatically provisions a Cloudflare Turnstile site named after the INSTANCE_NAME. It then pushes the TURNSTILE_SITE_KEY and TURNSTILE_SECRET_KEY as Worker secrets. This protects the /setup and /login routes.
Sources: scripts/setup-cf.js:180-235, README.md:171-180

Summary

Cloudflare Deployment Configuration in e-zer0 provides a robust, edge-native environment for AI-driven email management. By automating resource provisioning through setup-cf.js and utilizing Cloudflare's integrated D1, Vectorize, and KV services, the project ensures a secure, scalable, and private deployment. Users maintain full control over their infrastructure, with sensitive keys and data protected by Cloudflare's standard-compliant encryption and secret management systems.
Sources: README.md:20-25, AGENTS.md:14-22, scripts/setup-cf.js:5-15