Introduction to e-zer0
Relevant source files
The following files were used as context for generating this wiki page:
e-zer0 is a self-hosted, secure bridge that connects Artificial Intelligence (AI) agents to email accounts, including Gmail and Microsoft 365/Outlook. It functions as a Model Context Protocol (MCP) server, allowing agents to read, search, and manage communications without possessing raw user credentials. The system prioritizes privacy by running entirely on the user's Cloudflare account, ensuring no third-party service accesses email data or credentials during the bridging process.
Sources: README.md:1-12, AGENTS.md:5-9
System Architecture
e-zer0 is built on the Cloudflare Developer Platform and utilizes a server-side rendered architecture. It leverages the Hono framework for routing and JSX-based UI components. The system operates on Cloudflare Workers (V8 isolates) and avoids Node.js built-ins.
Technical Stack Components
| Component | Technology | Purpose |
|---|---|---|
| Compute | Cloudflare Workers | Serverless execution of logic and API handling. |
| Framework | Hono | Routing, middleware, and JSX-based UI rendering. |
| Database | Cloudflare D1 (SQLite) | Persistent storage for settings, sessions, and audits. |
| Vector Search | Cloudflare Vectorize | Semantic search capabilities for email content. |
| AI Models | Workers AI | Generation of embeddings (bge-base-en-v1.5). |
| MCP Server | @modelcontextprotocol/sdk | Standardized protocol for AI tool interaction. |
Sources: AGENTS.md:13-20, package.json:52-55, wrangler.toml:13-33
Request Flow and Integration
The following diagram illustrates how an AI Agent interacts with e-zer0 to access protected email providers.
The diagram shows the e-zer0 instance acting as a secure intermediary between the AI agent and the email providers, incorporating sanitization and auditing.
Sources: README.md:15-32, AGENTS.md:22-30, src/app.ts:74-84
Core Security Features
e-zer0 implements a "Zero Trust" architecture to protect sensitive user data.
- PII Redaction: The system automatically redacts sensitive information such as credit card numbers, passwords, and API keys before email content reaches the AI agent.
- Prompt Injection Protection: e-zer0 scans incoming emails for malicious instructions designed to hijack AI agents and assigns risk scores.
- Encrypted Storage: Credentials and OAuth tokens are stored in a Cloudflare D1 vault encrypted with AES-256-GCM.
- Audit Logging: Every action taken by an agent is recorded with timestamps, agent identity, and status.
- Bot Protection: Login and setup pages are protected by Cloudflare Turnstile.
Sources: README.md:34-51, AGENTS.md:55-65, src/app.ts:46-55
Deployment and Configuration
The application is deployed using the wrangler CLI or via GitHub Actions. Deployment involves provisioning Cloudflare resources and generating secure root keys.
Deployment Workflow
The sequence shows the automated provisioning of remote resources and local environment variables.
Sources: scripts/setup-cf.js:15-115, README.md:167-185
Critical Environment Variables
| Variable | Description | Source |
|---|---|---|
ENCRYPTION_KEY | 64-character hex string for AES-256-GCM encryption of tokens at rest. | Cloudflare Secret |
JWT_SECRET | Secret used for signing and verifying JSON Web Tokens for agent auth. | Cloudflare Secret |
INSTANCE_NAME | Prefix for provisioned resources (e.g., d1, vectorize, turnstile). | Environment Variable |
Sources: scripts/setup-cf.js:20-60, wrangler.toml:1-10
Integration with Email Providers
e-zer0 provides a unified abstraction layer over Gmail and Microsoft 365. Administrators must configure OAuth applications in the respective provider consoles (Google Cloud Console or Azure Portal) and input the credentials into the e-zer0 settings.
- Gmail: Requires enabling the Gmail API, Google Tasks API, and Google Calendar API.
- Microsoft: Requires App Registration in Entra ID with
Mail.ReadWrite,Tasks.ReadWrite, andCalendars.Readdelegated permissions.
Sources: src/routes/settings.tsx:55-80, src/routes/settings.tsx:185-235, README.md:116-125
Conclusion
e-zer0 provides a secure, self-hosted infrastructure for AI-driven email management. By utilizing Cloudflare's edge network and implementing robust sanitization and auditing, it allows users to leverage AI productivity tools while maintaining ownership and control over their sensitive communication data.
Sources: README.md:14-25, AGENTS.md:5-10