Setup & Login Flow

Relevant source files

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

• src/routes/setup.tsx
• src/routes/login.tsx
• src/app.ts
• scripts/setup-cf.js
• src/lib/crypto.test.ts
• README.md

The Setup and Login flows manage the initial provisioning and subsequent authentication of the e-zer0 administrator account. These processes secure the instance, ensuring only authorized users can configure email providers and manage AI agent access.

Initial Infrastructure Provisioning

The setup process begins before the application runs. The setup-cf.js script provisions necessary Cloudflare resources and generates root security keys.

Resource Provisioning

The script creates the following resources in the Cloudflare account:

• D1 Database: Stores user accounts, sessions, and encrypted credentials.
• Vectorize Index: Stores email embeddings for semantic search.
• KV Namespace: Used for rate limiting login attempts.
• Turnstile Site: Provides bot protection for setup and login pages.

Sources: scripts/setup-cf.js:108-166, README.md:162-172

Security Key Generation

The system requires two 64-character hexadecimal secrets:

1. ENCRYPTION_KEY: Encrypts provider access tokens at rest.
2. JWT_SECRET: Signs authentication tokens for MCP clients.

If these keys are missing during setup, the interface displays a critical security warning.
Sources: scripts/setup-cf.js:33-82, src/routes/setup.tsx:14-19

Administrator Account Creation

The setup route (/setup) handles the creation of the first administrator account. This route remains accessible only until the admin_users table contains at least one record.

Registration Workflow

1. User Input: The user provides a username and a password (minimum 8 characters).
2. Bot Protection: The system verifies the Cloudflare Turnstile token if configured.
3. Data Persistence: The system generates a salt and hashes the password using Web Crypto APIs.
4. Session Initiation: Upon successful insertion into D1, the system creates a session and redirects the user to the dashboard.

Sources: src/routes/setup.tsx:21-70, src/routes/setup.tsx:140-165

The diagram shows the logic gate preventing multiple admin creations and the sequence of credential validation.
Sources: src/routes/setup.tsx:116-166

Authentication Flow

The login route (/login) authenticates the administrator and manages session security.

Login Security Measures

The system implements several layers of protection against brute-force attacks and session hijacking:

• Rate Limiting: Failed attempts are tracked by IP and username in the RATE_LIMITER KV namespace.
• Turnstile: Verifies the user is human before processing credentials.
• Session Rotation: The system deletes all existing sessions for a user upon a new successful login.
• CSRF Protection: The application applies CSRF middleware to the /login and /logout routes.

Sources: src/routes/login.tsx:75-100, src/app.ts:40-47, src/routes/login.tsx:114-115

Authentication Procedure

When a user submits the login form, the server performs these steps:

1. Increments the rate limit counter for the IP/Username combination.
2. Retrieves the user record from the admin_users table.
3. Verifies the submitted password against the stored hash and salt using constant-time comparison.
4. Clears the rate limit counter on success.
5. Cleans up expired sessions from the database.
6. Sets a Set-Cookie header with the new session token.

Sources: src/routes/login.tsx:84-118, src/lib/crypto.test.ts:74-78

Redirection Logic

The login process supports a redirect_to parameter. The system validates that the target URL is same-origin to prevent open redirect vulnerabilities before performing the redirect.
Sources: src/routes/login.tsx:122-133

Summary of Configuration Elements

Element	Storage Location	Purpose
ENCRYPTION_KEY	Cloudflare Secrets	AES-256-GCM encryption of email tokens
JWT_SECRET	Cloudflare Secrets	Signing MCP agent access tokens
password_hash	D1 admin_users	PBKDF2/WebCrypto hash of admin password
salt	D1 admin_users	Unique salt per user for hashing
TURNSTILE_SITE_KEY	Cloudflare Secrets	Public key for frontend bot challenge

Sources: README.md:143-152, src/routes/setup.tsx:143-144, src/app.ts:40-47

Conclusion

The Setup & Login Flow ensures that the e-zer0 instance is properly initialized with root encryption keys and secured by a single administrator account. By leveraging Cloudflare's edge infrastructure for secrets, rate limiting, and bot protection, the system maintains a zero-trust architecture while providing a simplified browser-based setup experience.