Session & State Management

Relevant source files

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

• src/app.ts
• src/routes/login.tsx
• src/routes/setup.tsx
• src/types.ts
• src/routes/mcp-auth.test.ts
• src/lib/crypto.test.ts

Session and State Management in e-zer0 controls administrative access to the dashboard and manages the lifecycle of AI agent authorizations. The system distinguishes between web-based administrative sessions, which use traditional cookies, and agent-based state, which uses OAuth 2.0 and JWTs.

Sources: AGENTS.md, src/app.ts:36-58

Administrative Session Management

Administrative sessions secure the web UI and management dashboard. The application uses a custom session implementation backed by a Cloudflare D1 SQLite database.

Session Lifecycle

When an admin successfully logs in, the system creates a new session record in the sessions table and returns a Set-Cookie header to the browser.
Sources: src/routes/login.tsx:109-114

The following sequence diagram illustrates the login and session creation flow:

Security Controls

1. Session Rotation: The system deletes all existing sessions for a user upon a new successful login to prevent concurrent session abuse.
   Sources: src/routes/login.tsx:106-107
2. Expiration Cleanup: The application performs background cleanup of expired sessions during every login attempt.
   Sources: src/routes/login.tsx:110
3. CSRF Protection: Mutation routes such as settings, agents, and setup are protected by CSRF middleware.
   Sources: src/app.ts:39-46

Agent State & Authorization

State management for AI agents (MCP clients) follows the OAuth 2.0 framework. It manages the relationship between a specific agent and the email accounts it is permitted to access.

Authorization State Model

The system tracks which agents can access which mailboxes through the mcp_client_accounts join table. This mapping persists even if an email account is re-authorized.
Sources: src/types.ts:60-64, README.md:126-130

Key Data Structures

Field	Type	Description
mcp_client_id	number	References the internal ID of the MCP agent.
email_account_id	number	References the internal ID of the connected Gmail/Outlook account.
is_active	number	Boolean flag (0/1) indicating if the agent registration is valid.
last_used_at	string	ISO timestamp of the last time the agent successfully called a tool.
Sources: src/types.ts:47-64

Persistence Layer (D1 Schema)

State is persisted across the following primary tables in Cloudflare D1:

• admin_users: Stores admin credentials (hashed). Sources: src/types.ts:25-31
• sessions: Manages active administrative web sessions. Sources: src/types.ts:33-39
• mcp_clients: Registry of AI agents that have interacted with the server. Sources: src/types.ts:47-58
• mcp_client_accounts: Mapping of permissions between agents and email accounts. Sources: src/types.ts:60-64
• oauth_auth_codes: Short-lived state for the OAuth authorization flow. Sources: src/types.ts:66-74

Rate Limiting State

Transient state related to security (brute-force protection) is stored in a Cloudflare KV namespace named RATE_LIMITER.

• Login Protection: Failed login attempts are tracked by IP and username. Exceeding limits blocks access for 15 minutes.
  Sources: src/routes/login.tsx:90-94
• Agent Registration: Anonymous agent registration is limited by IP to prevent resource exhaustion in the database.
  Sources: src/routes/mcp-auth.test.ts:771-790

Summary

e-zer0 utilizes a tiered state management approach. Administrative state is handled through traditional database-backed sessions with proactive rotation and cleanup. Agent state is governed by an OAuth-compatible model that strictly maps agent identities to specific mailbox permissions, ensuring that AI tools operate within defined security boundaries. All persistent state resides in Cloudflare D1, while security-sensitive transient state is offloaded to Cloudflare KV.