Settings & Secrets Management
Relevant source files
The following files were used as context for generating this wiki page:
Settings & Secrets Management provides the infrastructure for securely storing and retrieving configuration data, OAuth credentials, and encryption keys. The system ensures that sensitive information, such as email provider tokens and administrative secrets, remains encrypted at rest and is only accessible through validated internal processes.
This module primarily interacts with the Cloudflare D1 database for persistent settings and uses Cloudflare Worker Secrets for root-level encryption keys. The architecture follows a Zero Trust model where raw credentials never leave the controlled environment. Sources: README.md, AGENTS.md
Encryption Architecture
The project employs a multi-layered encryption strategy. Root secrets are stored as Cloudflare Worker Secrets, while application-level secrets and third-party tokens are stored in the app_settings and email_accounts database tables respectively.
Cryptographic Primitive
All cryptographic operations use the Web Crypto API (crypto.subtle). Sensitive data is encrypted using AES-256-GCM. This includes:
- Provider Access Tokens: Encrypted before storage in the D1 database.
- OAuth Client Secrets: Encrypted in the
app_settingstable. - JWT Secrets: Used for signing short-lived tokens for Model Context Protocol (MCP) agents.
Sources: AGENTS.md, src/lib/crypto.test.ts:74-128, README.md
Key Provisioning Flow
The setup-cf.js script manages the generation and deployment of these keys. In local development, it populates a .dev.vars file. In production, it pushes these values to Cloudflare Secrets.
The diagram shows how the system prevents accidental invalidation of existing data by skipping secret updates if a key already exists in Cloudflare. Sources: scripts/setup-cf.js:13-176
Application Settings
Application-level settings are stored in the app_settings table. These include OAuth Client IDs and Secrets for Google and Microsoft. The src/lib/settings.ts utility functions handle the logic of encrypting these values before they reach the database.
Core Settings Functions
| Function | Description | Implementation Detail |
|---|---|---|
getSetting | Retrieves and decrypts a value. | Uses ENCRYPTION_KEY for decryption. |
setSetting | Encrypts and persists a value. | Performs an INSERT OR REPLACE in D1. |
hasSetting | Checks for existence. | Returns a boolean without decryption. |
Sources: src/lib/settings.ts, src/routes/settings.tsx:7-9
Provider Configuration
Configuration is performed through the dashboard UI. Administrators input OAuth credentials which the system then secures.
This sequence ensures that raw client secrets never touch the database disk in plain text. Sources: src/routes/settings.tsx:327-372
Secrets and Tokens in Database
The system manages several types of sensitive data within the D1 database. Each type has specific encryption requirements.
Data Model for Secrets
| Table | Field | Encryption | Purpose |
|---|---|---|---|
app_settings | value | AES-256-GCM | Stores OAuth client secrets. |
email_accounts | encrypted_access_token | AES-256-GCM | Stores OAuth access tokens. |
email_accounts | encrypted_refresh_token | AES-256-GCM | Stores OAuth refresh tokens. |
admin_users | password_hash | PBKDF2 | Stores hashed admin passwords. |
Sources: README.md, src/mcp/tools.ts:114-118, src/routes/setup.tsx:162-165
Decryption Access Pattern
When an MCP tool needs to access a provider API (e.g., Gmail), it must first decrypt the stored access token. This process is encapsulated in the getAccountToken helper. If decryption fails—typically due to a root key rotation—the account status is updated to error, prompting the user to reconnect. Sources: src/mcp/tools.ts:101-140
Infrastructure Bindings
The wrangler.toml file defines the environment bindings required for secrets and settings management. These bindings allow the Hono application to access Cloudflare resources directly via the context object (c.env).
Required Bindings
- D1 Database (
DB): Persistent storage for encrypted settings. - KV Namespace (
RATE_LIMITER): Used for brute-force protection on authentication routes. - Vectorize (
VECTOR_INDEX): Stores semantic embeddings for email search. - Secrets:
ENCRYPTION_KEY,JWT_SECRET, andTURNSTILE_SECRET_KEY.
Sources: wrangler.toml:14-41, src/app.ts:40-45
Conclusion
Settings & Secrets Management serves as the security foundation for e-zer0. By combining Cloudflare Worker Secrets for root keys with AES-256-GCM encryption for database-stored credentials, the system maintains a high security posture. This design ensures that even if the database is compromised, sensitive provider tokens and client secrets remain inaccessible without the corresponding Worker Secrets. Sources: README.md, AGENTS.md