Cryptography & Encryption
Relevant source files
The following files were used as context for generating this wiki page:
e-zer0 implements a zero-trust architecture to protect sensitive email credentials and agent communications. The system encrypts all provider access tokens at rest and uses secure hashing for administrative credentials. By running on the Cloudflare Workers edge runtime, the project utilizes the standardized Web Crypto API for all cryptographic operations.
Sources: README.md:52-57, src/lib/crypto.ts:1-3
Secure Storage & Encryption at Rest
The system protects sensitive data, such as OAuth access tokens and application settings, using AES-256-GCM encryption. This ensures that even if the Cloudflare D1 database is accessed, the underlying credentials remain unreadable without the environment's unique ENCRYPTION_KEY.
AES-GCM Implementation
Encryption operations use a random 12-byte Initialization Vector (IV) for every call. The system concatenates the IV with the ciphertext and encodes the result as a hexadecimal string for database storage.
The diagram above shows the flow of data from raw plaintext to encrypted storage in the D1 database.
Sources: src/lib/crypto.ts:74-87, README.md:27-28
Key Functions
| Function | Description |
|---|---|
encrypt(plaintext, keyHex) | Encrypts text using AES-256-GCM with a random IV. |
decrypt(cipherHex, keyHex) | Extracts the IV and decrypts hex-encoded ciphertext. |
getAesKey(keyHex) | Imports a 64-character hex string as a CryptoKey object. |
Sources: src/lib/crypto.ts:65-98
Credential Hashing
e-zer0 secures administrative account passwords using the PBKDF2 (Password-Based Key Derivation Function 2) algorithm. This process prevents the storage of raw passwords and protects against rainbow table attacks by using unique salts for every user.
Password Hashing Logic
- The system generates a random 16-byte salt for the new user.
- It derives bits using PBKDF2 with 100,000 iterations and the SHA-256 hash algorithm.
- It stores both the resulting hash and the salt in the
admin_userstable.
Sources: src/lib/crypto.ts:3-5, src/lib/crypto.ts:31-50, src/routes/setup.tsx:142-146
Constant-Time Verification
To prevent timing attacks, the system compares password hashes using a constant-time algorithm. This ensures the verification time does not reveal information about the correctness of the input.
Sources: src/lib/crypto.ts:54-61, src/lib/crypto.test.ts:76-80
Identity & Token Generation
The system generates unique identifiers and secure tokens for Model Context Protocol (MCP) clients and OAuth flows.
Token Types
| Token Type | Prefix | Length (Bytes) | Format |
|---|---|---|---|
| Generic Token | None | 32 | 64-char Hex |
| Client ID | ez_ | 16 | Prefix + 32-char Hex |
| Client Secret | ezs_ | 32 | Prefix + 64-char Hex |
Sources: src/lib/crypto.ts:102-118, src/lib/crypto.test.ts:133-146
Authentication (JWT)
MCP agents authenticate via short-lived JSON Web Tokens (JWT). The system signs these tokens using HMAC-SHA256 and the JWT_SECRET.
The sequence diagram illustrates the issuance of a JWT to an MCP agent after validating client credentials.
Sources: src/routes/mcp.ts:73-86, src/routes/mcp.ts:251-260
Infrastructure Security
During deployment, the setup-cf.js script provisions the necessary cryptographic secrets within the Cloudflare environment.
Secret Provisioning
- Local Development: Keys are generated and stored in a git-ignored
.dev.varsfile. - Production: Keys are pushed to Cloudflare using
wrangler secret put. The script checks for existing keys to prevent overwriting, which would invalidate all existing encrypted data in the database.
Sources: scripts/setup-cf.js:130-165, src/routes/setup.tsx:16-21
Configuration Summary
| Environment Variable | Requirement | Usage |
|---|---|---|
ENCRYPTION_KEY | 64-char Hex | AES-GCM encryption for tokens and settings. |
JWT_SECRET | 64-char Hex | Signing and verifying MCP access tokens. |
Sources: scripts/setup-cf.js:46-51, src/lib/crypto.ts:66-68
Conclusion
Cryptography in e-zer0 is built on top of the Web Crypto API to ensure high-performance, standards-compliant security at the edge. By combining AES-GCM for data at rest, PBKDF2 for password protection, and HMAC-signed JWTs for agent sessions, the system maintains a robust security posture for self-hosted email management.