OAuth & Authorization

Relevant source files

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

• src/routes/oauth-callback.ts
• src/routes/mcp.ts
• src/routes/authorize.tsx
• src/routes/settings.tsx
• src/app.ts
• src/routes/mcp-auth.test.ts

OAuth & Authorization in e-zer0 manages the secure connection between the platform, external email providers (Google and Microsoft), and Model Context Protocol (MCP) clients. The system handles two primary flows: the connection of user mailboxes via provider-specific OAuth 2.0 and the authorization of AI agents to access these mailboxes using standardized OAuth protocols.

External Provider Authentication

The system allows users to link Gmail and Outlook accounts by acting as an OAuth client. It securely stores encrypted access and refresh tokens in the Cloudflare D1 database.

Connection Workflow

1. Configuration: You enter the Client ID and Client Secret for Google or Microsoft in the Settings page.
2. Initialization: The /oauth/google/start or /oauth/microsoft/start routes generate a unique state token and redirect you to the provider's consent screen.
3. Callback Handling: The provider redirects back to /oauth/google/callback or /oauth/microsoft/callback.
4. Token Exchange: The system exchanges the authorization code for access and refresh tokens.
5. Storage: The system encrypts tokens using AES-256-GCM before saving them to the email_accounts table.

Sources: src/routes/oauth-callback.ts:13-145, src/routes/settings.tsx:238-316

Provider Scopes

The application requests specific permissions to enable email and calendar management.

Provider	Required Scopes	Purpose
Google	gmail.readonly, gmail.modify, gmail.settings.basic, tasks, calendar.events.readonly	Read/modify email, manage tasks, and read calendar events.
Microsoft	Mail.Read, Mail.ReadWrite, MailboxSettings.ReadWrite, Tasks.ReadWrite, Calendars.Read	Full email access, inbox rules, To Do management, and calendar reading.

Sources: src/routes/settings.tsx:128-142, src/routes/settings.tsx:216-231

MCP Client Authorization

e-zer0 acts as an Authorization Server for AI agents (MCP Clients). It supports the Authorization Code flow with Proof Key for Code Exchange (PKCE).

Authorization Request Flow

AI agents initiate access by requesting authorization. An admin user must manually approve the agent and select which mailboxes the agent can access.

The server validates client_id, redirect_uri, and enforces S256 PKCE for public clients.
Sources: src/routes/authorize.tsx:50-211, src/routes/mcp-auth.test.ts:446-512

Token Issuance

The /mcp/token endpoint exchanges authorization codes or client credentials for JWT access tokens.

• Access Token TTL: 30 days for client credentials, shorter for authorized agents.
• Refresh Tokens: Issued for authorization_code and refresh_token grants.
• Security: Tokens are signed using HMAC-SHA256 with a JWT_SECRET stored as a Cloudflare Secret.

Sources: src/routes/mcp.ts:153-288, src/routes/mcp-auth.test.ts:983-1014

Security Architecture

Authorization is protected by multiple layers of security to prevent unauthorized access and data leakage.

Protective Measures

• CSRF Protection: OAuth state tokens are stored in signed, httpOnly, Lax cookies during the provider handshake to prevent Cross-Site Request Forgery.
• Rate Limiting: The system tracks failed token attempts by IP and Client ID using Cloudflare KV.
• Token Encryption: All sensitive provider tokens are encrypted at rest using crypto.subtle.
• Client Revocation: The server performs a synchronous database check for is_active = 1 on every MCP request, even if the JWT is cryptographically valid.

Sources: src/routes/oauth-callback.ts:31-40, src/routes/mcp.ts:187-200, src/routes/mcp.ts:311-318, src/app.ts:48-54

Data Model for Authorization

The system uses specific D1 tables to track identity and permissions.

Table	Description
mcp_clients	Stores registered agents, their secret hashes (if confidential), and status.
mcp_client_accounts	Junction table mapping agents to specific permitted email accounts.
oauth_auth_codes	Temporary storage for authorization codes during the handshake.
email_accounts	Stores encrypted credentials for connected Gmail/Outlook mailboxes.

Sources: src/routes/mcp-auth.test.ts:11-40, src/routes/authorize.tsx:185-200

Discovery and Metadata

The server exposes standard OAuth 2.0 metadata endpoints to facilitate automatic configuration for MCP clients.

• Authorization Server: /.well-known/oauth-authorization-server
• Protected Resource: /.well-known/oauth-protected-resource

These endpoints advertise supported grant types (authorization_code, refresh_token, client_credentials) and PKCE methods (S256).
Sources: src/app.ts:76-105

Conclusion

The OAuth & Authorization system provides a secure, audited bridge between AI agents and private email data. By combining standard OAuth 2.0 flows with Cloudflare-native security features like D1, KV, and Web Crypto, e-zer0 ensures that mailbox access is explicitly granted by administrators and protected against common web vulnerabilities.