converse-mcp-server 1.3.0 → 1.3.2

package/.env.example

@@ -1,37 +1,130 @@
-# Zen MCP Server Environment Configuration
+# Converse MCP Server Environment Configuration
 # Copy this file to .env and fill in your values
 
+# ========================================
 # API Keys - At least one is required
-#
-# IMPORTANT: Choose ONE approach:
-# - Native APIs (Gemini/OpenAI/XAI) for direct access
-# - DIAL for unified enterprise access
-# - OpenRouter for unified cloud access
-# Having multiple unified providers creates ambiguity about which serves each model.
-#
-# Option 1: Use native APIs (recommended for direct access)
-# Get your Gemini API key from: https://makersuite.google.com/app/apikey
-GEMINI_API_KEY=your_gemini_api_key_here
+# ========================================
 
-# Get your OpenAI API key from: https://platform.openai.com/api-keys
-OPENAI_API_KEY=your_openai_api_key_here
+# OpenAI - https://platform.openai.com/api-keys
+OPENAI_API_KEY=sk-proj-...
 
-# Get your X.AI API key from: https://console.x.ai/
-XAI_API_KEY=your_xai_api_key_here
+# Google Gemini - https://makersuite.google.com/app/apikey
+GOOGLE_API_KEY=AIzaSy...
 
-# Get your Anthropic API key from: https://console.anthropic.com/
-ANTHROPIC_API_KEY=your_anthropic_api_key_here
+# X.AI Grok - https://console.x.ai/
+XAI_API_KEY=xai-...
 
-# Get your Mistral API key from: https://console.mistral.ai/
-MISTRAL_API_KEY=your_mistral_api_key_here
+# Anthropic Claude - https://console.anthropic.com/
+ANTHROPIC_API_KEY=sk-ant-...
 
-# Get your DeepSeek API key from: https://platform.deepseek.com/
-DEEPSEEK_API_KEY=your_deepseek_api_key_here
+# Mistral - https://console.mistral.ai/
+MISTRAL_API_KEY=...
 
-# Get your OpenRouter API key from: https://openrouter.ai/keys
-OPENROUTER_API_KEY=your_openrouter_api_key_here
+# DeepSeek - https://platform.deepseek.com/
+DEEPSEEK_API_KEY=...
 
-# OpenRouter requires a referer for compliance (your app URL or GitHub repo)
+# OpenRouter - https://openrouter.ai/keys
+OPENROUTER_API_KEY=sk-or-...
 OPENROUTER_REFERER=https://github.com/FallDownTheSystem/converse
 
+# ========================================
+# Server Configuration
+# ========================================
+
+# Transport mode: http or stdio (default: http)
+MCP_TRANSPORT=http
+
+# Server settings
+PORT=3157
+HOST=localhost
+LOG_LEVEL=info
+NODE_ENV=development
+
+# ========================================
+# Authentication Configuration (for remote deployments)
+# ========================================
+
+# Authentication strategy: none, bearer, api_key, oauth2 (default: none)
+MCP_AUTH_STRATEGY=none
+MCP_AUTH_REQUIRE=false
+
+# JWT Configuration (for bearer token and OAuth2)
+# Generate a secure secret: openssl rand -base64 32
+MCP_JWT_SECRET=
+MCP_JWT_ALGORITHM=HS256
+MCP_JWT_EXPIRES_IN=24h
+MCP_JWT_ISSUER=converse-mcp-server
+
+# API Key Authentication
+# Comma-separated list of valid API keys
+MCP_API_KEYS=
+
+# OAuth2 Configuration (example for Google)
+MCP_OAUTH_CLIENT_ID=
+MCP_OAUTH_CLIENT_SECRET=
+MCP_OAUTH_AUTH_URL=https://accounts.google.com/o/oauth2/v2/auth
+MCP_OAUTH_TOKEN_URL=https://oauth2.googleapis.com/token
+MCP_OAUTH_CALLBACK_URL=https://your-server.com/oauth/callback
+MCP_OAUTH_SCOPE=openid profile email
+MCP_OAUTH_USERINFO_URL=https://www.googleapis.com/oauth2/v2/userinfo
+
+# Session-based Authentication Control
+MCP_SESSION_AUTH_ENABLED=true
+MCP_SESSION_AUTH_REQUIRE_FOR_SESSION=false
+MCP_SESSION_AUTH_REQUIRE_FOR_OPERATIONS=true
 
+# ========================================
+# HTTP Transport Configuration
+# ========================================
+
+# Request handling
+HTTP_REQUEST_TIMEOUT=300000      # 5 minutes
+HTTP_MAX_REQUEST_SIZE=10mb
+
+# Session management
+HTTP_SESSION_TIMEOUT=1800000     # 30 minutes
+HTTP_SESSION_CLEANUP_INTERVAL=300000  # 5 minutes
+HTTP_MAX_CONCURRENT_SESSIONS=100
+
+# CORS configuration
+HTTP_ENABLE_CORS=true
+HTTP_CORS_ORIGINS=*
+HTTP_CORS_METHODS=GET,POST,DELETE,OPTIONS
+HTTP_CORS_HEADERS=Content-Type,mcp-session-id,Authorization,X-API-Key
+HTTP_CORS_CREDENTIALS=false
+
+# Security settings
+HTTP_DNS_REBINDING_PROTECTION=false
+HTTP_ALLOWED_HOSTS=127.0.0.1,localhost
+HTTP_RATE_LIMIT_ENABLED=false
+HTTP_RATE_LIMIT_WINDOW=900000    # 15 minutes
+HTTP_RATE_LIMIT_MAX_REQUESTS=1000
+
+# ========================================
+# Advanced Configuration
+# ========================================
+
+# MCP Server settings
+MCP_SERVER_NAME=converse-mcp-server
+MCP_SERVER_VERSION=1.0.0
+MAX_MCP_OUTPUT_TOKENS=25000
+
+# Provider-specific settings
+GOOGLE_LOCATION=us-central1
+XAI_BASE_URL=https://api.x.ai/v1
+
+# ========================================
+# Production Example Configuration
+# ========================================
+
+# For production deployments, uncomment and modify:
+#
+# NODE_ENV=production
+# MCP_AUTH_STRATEGY=oauth2
+# MCP_AUTH_REQUIRE=true
+# MCP_JWT_SECRET=<generate-with-openssl-rand-base64-32>
+# HTTP_RATE_LIMIT_ENABLED=true
+# HTTP_DNS_REBINDING_PROTECTION=true
+# HTTP_CORS_ORIGINS=https://your-app.com
+# HTTP_ENABLE_CORS=true
+# LOG_LEVEL=warn

package/README.md

@@ -180,6 +180,30 @@ There are several ways to add the Converse MCP Server to Claude:
 }
 ```
 
+#### Option E: Local HTTP Development (Advanced)
+
+For local development with HTTP transport:
+
+1. **First, start the server manually**:
+   ```bash
+   # In a terminal, navigate to the project directory
+   cd converse
+   npm run dev  # Starts server on http://localhost:3157/mcp
+   ```
+
+2. **Then configure Claude to connect to it**:
+   ```json
+   {
+     "mcpServers": {
+       "converse-local": {
+         "url": "http://localhost:3157/mcp"
+       }
+     }
+   }
+   ```
+
+**Important**: HTTP transport requires the server to be running before Claude can connect to it. Keep the terminal with the server open while using Claude.
+
 #### Installation Steps
 
 1. **For Claude Code**: 
@@ -197,6 +221,14 @@ There are several ways to add the Converse MCP Server to Claude:
      - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
      - Linux: `~/.config/Claude/claude_desktop_config.json`
 
+**Windows Troubleshooting**: If `npx converse-mcp-server` doesn't work on Windows, try using:
+```json
+{
+  "command": "cmd",
+  "args": ["/c", "npx", "converse-mcp-server"]
+}
+```
+
 For more detailed instructions, see the [official MCP configuration guide](https://docs.anthropic.com/en/docs/claude-code/mcp#configure-mcp-servers).
 
 ## 🛠️ Available Tools
@@ -349,7 +381,8 @@ npm start -- --transport=stdio
 
 **Transport Modes**: 
 - **HTTP Transport** (default): `http://localhost:3157/mcp` - Better for development and debugging
-- **Stdio Transport**: Use `--transport=stdio` or set `MCP_TRANSPORT=stdio` for traditional stdio communication
+  - **Note**: When using HTTP transport, the server must be started manually (e.g., `npm start` or `npm run dev`) as it runs as a standalone process, unlike stdio which is launched as a subprocess by Claude
+- **Stdio Transport**: Use `--transport=stdio` or set `MCP_TRANSPORT=stdio` for traditional stdio communication (launched automatically by Claude)
 
 ### Testing with Real APIs
 
@@ -500,6 +533,90 @@ converse/
 | `GOOGLE_LOCATION` | Google API region | `us-central1` | `us-central1` |
 | `XAI_BASE_URL` | XAI API endpoint | `https://api.x.ai/v1` | Custom endpoint |
 
+### 🔐 Authentication for Remote Deployments
+
+The Converse MCP Server supports multiple authentication strategies for secure remote deployments:
+
+#### Authentication Strategies
+
+| Strategy | Description | Configuration |
+|----------|-------------|---------------|
+| `none` | No authentication (default) | No additional config needed |
+| `bearer` | JWT Bearer token | Requires `MCP_JWT_SECRET` |
+| `api_key` | API key authentication | Requires `MCP_API_KEYS` |
+| `oauth2` | OAuth 2.0 flow | Requires OAuth provider config |
+
+#### Environment Variables for Authentication
+
+```bash
+# Authentication Strategy
+MCP_AUTH_STRATEGY=bearer      # Options: none, bearer, api_key, oauth2
+MCP_AUTH_REQUIRE=true         # Require auth for all requests
+
+# JWT Configuration (for bearer and oauth2)
+MCP_JWT_SECRET=your-secret-key-at-least-32-chars
+MCP_JWT_ALGORITHM=HS256       # Default: HS256
+MCP_JWT_EXPIRES_IN=24h        # Default: 24h
+MCP_JWT_ISSUER=converse-mcp   # Default: converse-mcp-server
+
+# API Key Authentication
+MCP_API_KEYS=key1,key2,key3   # Comma-separated list
+
+# OAuth2 Configuration
+MCP_OAUTH_CLIENT_ID=your-client-id
+MCP_OAUTH_CLIENT_SECRET=your-client-secret
+MCP_OAUTH_AUTH_URL=https://accounts.google.com/o/oauth2/v2/auth
+MCP_OAUTH_TOKEN_URL=https://oauth2.googleapis.com/token
+MCP_OAUTH_CALLBACK_URL=https://your-server.com/oauth/callback
+MCP_OAUTH_SCOPE=openid profile email
+MCP_OAUTH_USERINFO_URL=https://www.googleapis.com/oauth2/v2/userinfo
+
+# Session-based Auth Control
+MCP_SESSION_AUTH_ENABLED=true              # Enable session auth
+MCP_SESSION_AUTH_REQUIRE_FOR_SESSION=false # Allow session creation without auth
+MCP_SESSION_AUTH_REQUIRE_FOR_OPERATIONS=true # Require auth for operations
+```
+
+#### Authentication Examples
+
+**Bearer Token (Recommended for APIs)**
+```bash
+# Generate a token (you'll need to implement token generation)
+curl -X POST http://localhost:3157/mcp \
+  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
+```
+
+**API Key**
+```bash
+curl -X POST http://localhost:3157/mcp \
+  -H "X-API-Key: your-api-key"
+```
+
+**OAuth2 Flow**
+1. Direct user to `/oauth/authorize`
+2. User authenticates with OAuth provider
+3. Server exchanges code for token at `/oauth/callback`
+4. Client receives MCP JWT token for subsequent requests
+
+#### Security Best Practices
+
+1. **Always use HTTPS** in production deployments
+2. **Set strong JWT secrets** (minimum 32 characters)
+3. **Use short token expiration** times (24h or less)
+4. **Enable rate limiting** for additional protection
+5. **Configure CORS** appropriately for your clients
+
+Example production configuration:
+```bash
+NODE_ENV=production
+MCP_AUTH_STRATEGY=oauth2
+MCP_AUTH_REQUIRE=true
+MCP_JWT_SECRET=$(openssl rand -base64 32)
+HTTP_RATE_LIMIT_ENABLED=true
+HTTP_DNS_REBINDING_PROTECTION=true
+HTTP_CORS_ORIGINS=https://your-app.com
+```
+
 ### Model Selection
 
 Use `"auto"` for automatic model selection, or specify exact models:

package/docs/AUTHENTICATION.md

@@ -0,0 +1,408 @@
+# Authentication Guide for Converse MCP Server
+
+This guide covers the authentication options available for securing remote deployments of the Converse MCP Server.
+
+## Overview
+
+The Converse MCP Server supports multiple authentication strategies to secure remote deployments:
+
+- **None** (default) - No authentication required
+- **Bearer Token** - JWT-based authentication
+- **API Key** - Simple shared key authentication
+- **OAuth 2.0** - Full OAuth2 authorization code flow
+
+## Configuration
+
+All authentication is configured through environment variables. The primary variable is `MCP_AUTH_STRATEGY` which determines the authentication method.
+
+## Authentication Strategies
+
+### 1. No Authentication (Default)
+
+```bash
+MCP_AUTH_STRATEGY=none
+MCP_AUTH_REQUIRE=false
+```
+
+This is the default configuration suitable for:
+- Local development
+- Internal networks with other security measures
+- Testing environments
+
+### 2. Bearer Token Authentication
+
+JWT-based authentication suitable for API clients.
+
+```bash
+MCP_AUTH_STRATEGY=bearer
+MCP_AUTH_REQUIRE=true
+MCP_JWT_SECRET=your-secret-key-at-least-32-chars
+MCP_JWT_ALGORITHM=HS256
+MCP_JWT_EXPIRES_IN=24h
+MCP_JWT_ISSUER=converse-mcp-server
+```
+
+**Client Usage:**
+```bash
+curl -X POST http://localhost:3157/mcp \
+  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+```
+
+**Token Generation:**
+You'll need to implement token generation separately. Example Node.js code:
+
+```javascript
+import jwt from 'jsonwebtoken';
+
+const token = jwt.sign(
+  { 
+    sub: 'user123',
+    name: 'John Doe',
+    email: 'john@example.com'
+  },
+  process.env.MCP_JWT_SECRET,
+  {
+    algorithm: 'HS256',
+    expiresIn: '24h',
+    issuer: 'converse-mcp-server'
+  }
+);
+```
+
+### 3. API Key Authentication
+
+Simple shared key authentication suitable for server-to-server communication.
+
+```bash
+MCP_AUTH_STRATEGY=api_key
+MCP_AUTH_REQUIRE=true
+MCP_API_KEYS=key1,key2,key3  # Comma-separated list
+```
+
+**Client Usage:**
+```bash
+curl -X POST http://localhost:3157/mcp \
+  -H "X-API-Key: key1" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+```
+
+### 4. OAuth 2.0 Authentication
+
+Full OAuth2 authorization code flow suitable for web applications.
+
+```bash
+MCP_AUTH_STRATEGY=oauth2
+MCP_AUTH_REQUIRE=true
+
+# JWT for MCP tokens
+MCP_JWT_SECRET=your-secret-key-at-least-32-chars
+
+# OAuth Provider Configuration
+MCP_OAUTH_CLIENT_ID=your-client-id
+MCP_OAUTH_CLIENT_SECRET=your-client-secret
+MCP_OAUTH_AUTH_URL=https://accounts.google.com/o/oauth2/v2/auth
+MCP_OAUTH_TOKEN_URL=https://oauth2.googleapis.com/token
+MCP_OAUTH_CALLBACK_URL=https://your-server.com/oauth/callback
+MCP_OAUTH_SCOPE=openid profile email
+MCP_OAUTH_USERINFO_URL=https://www.googleapis.com/oauth2/v2/userinfo
+```
+
+**OAuth Flow:**
+
+1. **Initiate Authorization:**
+   ```
+   GET /oauth/authorize?state=random-state
+   ```
+   
+2. **User Authenticates:**
+   User is redirected to OAuth provider (Google, GitHub, etc.)
+
+3. **Callback Handling:**
+   After authentication, provider redirects to:
+   ```
+   GET /oauth/callback?code=auth-code&state=random-state
+   ```
+
+4. **Token Response:**
+   Server returns MCP JWT token:
+   ```json
+   {
+     "access_token": "eyJhbGc...",
+     "token_type": "Bearer",
+     "expires_in": 86400,
+     "user": {
+       "sub": "user123",
+       "email": "user@example.com",
+       "name": "John Doe"
+     }
+   }
+   ```
+
+5. **Use Token:**
+   ```bash
+   curl -X POST http://localhost:3157/mcp \
+     -H "Authorization: Bearer eyJhbGc..." \
+     -H "Content-Type: application/json" \
+     -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+   ```
+
+## Session-Based Authentication
+
+The server supports flexible session-based authentication:
+
+```bash
+# Enable session auth
+MCP_SESSION_AUTH_ENABLED=true
+
+# Allow creating sessions without auth (default: false)
+MCP_SESSION_AUTH_REQUIRE_FOR_SESSION=false
+
+# Require auth for operations (default: true)
+MCP_SESSION_AUTH_REQUIRE_FOR_OPERATIONS=true
+```
+
+This allows:
+- Clients to create sessions without authentication
+- But requires authentication for actual operations
+- Useful for allowing initial connection but securing data access
+
+## Security Best Practices
+
+### 1. Use HTTPS in Production
+
+Always deploy with TLS/SSL encryption:
+```nginx
+server {
+    listen 443 ssl http2;
+    ssl_certificate /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+    
+    location / {
+        proxy_pass http://localhost:3157;
+        proxy_set_header Authorization $http_authorization;
+    }
+}
+```
+
+### 2. Generate Strong Secrets
+
+```bash
+# Generate a secure JWT secret
+openssl rand -base64 32
+
+# Generate API keys
+openssl rand -hex 32
+```
+
+### 3. Configure CORS Properly
+
+```bash
+HTTP_CORS_ORIGINS=https://your-app.com,https://app.your-domain.com
+HTTP_CORS_CREDENTIALS=true  # If using cookies
+```
+
+### 4. Enable Rate Limiting
+
+```bash
+HTTP_RATE_LIMIT_ENABLED=true
+HTTP_RATE_LIMIT_WINDOW=900000      # 15 minutes
+HTTP_RATE_LIMIT_MAX_REQUESTS=1000  # Per window
+```
+
+### 5. Enable DNS Rebinding Protection
+
+```bash
+HTTP_DNS_REBINDING_PROTECTION=true
+HTTP_ALLOWED_HOSTS=your-server.com,api.your-server.com
+```
+
+## Common OAuth Providers
+
+### Google OAuth 2.0
+
+1. Create project at https://console.cloud.google.com
+2. Enable Google+ API
+3. Create OAuth 2.0 credentials
+4. Configure:
+
+```bash
+MCP_OAUTH_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
+MCP_OAUTH_CLIENT_SECRET=your-google-client-secret
+MCP_OAUTH_AUTH_URL=https://accounts.google.com/o/oauth2/v2/auth
+MCP_OAUTH_TOKEN_URL=https://oauth2.googleapis.com/token
+MCP_OAUTH_USERINFO_URL=https://www.googleapis.com/oauth2/v2/userinfo
+```
+
+### GitHub OAuth
+
+```bash
+MCP_OAUTH_CLIENT_ID=your-github-client-id
+MCP_OAUTH_CLIENT_SECRET=your-github-client-secret
+MCP_OAUTH_AUTH_URL=https://github.com/login/oauth/authorize
+MCP_OAUTH_TOKEN_URL=https://github.com/login/oauth/access_token
+MCP_OAUTH_USERINFO_URL=https://api.github.com/user
+MCP_OAUTH_SCOPE=read:user user:email
+```
+
+### Auth0
+
+```bash
+MCP_OAUTH_CLIENT_ID=your-auth0-client-id
+MCP_OAUTH_CLIENT_SECRET=your-auth0-client-secret
+MCP_OAUTH_AUTH_URL=https://your-domain.auth0.com/authorize
+MCP_OAUTH_TOKEN_URL=https://your-domain.auth0.com/oauth/token
+MCP_OAUTH_USERINFO_URL=https://your-domain.auth0.com/userinfo
+MCP_OAUTH_SCOPE=openid profile email
+```
+
+## Custom Authentication
+
+For custom authentication logic, implement a custom validator:
+
+```javascript
+const httpTransport = new HTTPTransportServer({
+  auth: {
+    strategy: 'custom',
+    customValidator: async (req) => {
+      // Your custom logic here
+      const token = req.headers['x-custom-token'];
+      
+      // Validate token against your system
+      const user = await validateCustomToken(token);
+      
+      return {
+        authenticated: !!user,
+        user: user,
+        // Additional data
+      };
+    }
+  }
+});
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **401 Unauthorized**
+   - Check auth strategy matches client implementation
+   - Verify token/API key is correct
+   - Check token expiration
+
+2. **CORS Errors**
+   - Ensure `HTTP_CORS_ORIGINS` includes your client origin
+   - Add `Authorization` to `HTTP_CORS_HEADERS`
+
+3. **OAuth Redirect Issues**
+   - Verify `MCP_OAUTH_CALLBACK_URL` matches OAuth provider config
+   - Check redirect URI is whitelisted in provider
+
+4. **Session Issues**
+   - Ensure `mcp-session-id` header is included
+   - Check session timeout configuration
+
+### Debug Mode
+
+Enable debug logging for authentication:
+```bash
+LOG_LEVEL=debug
+```
+
+This will log:
+- Authentication attempts
+- Token validation results
+- Session creation/cleanup
+- OAuth flow steps
+
+## Example Configurations
+
+### Development (Local)
+```bash
+MCP_AUTH_STRATEGY=none
+NODE_ENV=development
+LOG_LEVEL=debug
+```
+
+### Staging (API Key)
+```bash
+MCP_AUTH_STRATEGY=api_key
+MCP_API_KEYS=staging-key-1,staging-key-2
+MCP_AUTH_REQUIRE=true
+HTTP_RATE_LIMIT_ENABLED=true
+LOG_LEVEL=info
+```
+
+### Production (OAuth2)
+```bash
+NODE_ENV=production
+MCP_AUTH_STRATEGY=oauth2
+MCP_AUTH_REQUIRE=true
+MCP_JWT_SECRET=$(openssl rand -base64 32)
+MCP_OAUTH_CLIENT_ID=prod-client-id
+MCP_OAUTH_CLIENT_SECRET=prod-client-secret
+HTTP_RATE_LIMIT_ENABLED=true
+HTTP_DNS_REBINDING_PROTECTION=true
+HTTP_CORS_ORIGINS=https://app.example.com
+LOG_LEVEL=warn
+```
+
+## Integration Examples
+
+### JavaScript/TypeScript Client
+
+```typescript
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+
+const transport = new StreamableHTTPClientTransport(
+  new URL('https://your-server.com/mcp'),
+  {
+    headers: {
+      'Authorization': 'Bearer your-jwt-token'
+      // or 'X-API-Key': 'your-api-key'
+    }
+  }
+);
+
+const client = new Client({
+  name: 'my-client',
+  version: '1.0.0'
+});
+
+await client.connect(transport);
+```
+
+### Python Client
+
+```python
+import httpx
+from mcp import Client
+
+headers = {
+    "Authorization": "Bearer your-jwt-token"
+    # or "X-API-Key": "your-api-key"
+}
+
+async with httpx.AsyncClient(headers=headers) as http_client:
+    client = Client("my-client", "1.0.0")
+    await client.connect(
+        url="https://your-server.com/mcp",
+        http_client=http_client
+    )
+```
+
+## Deployment Checklist
+
+- [ ] Choose appropriate authentication strategy
+- [ ] Generate secure secrets (32+ characters)
+- [ ] Configure OAuth provider (if using OAuth2)
+- [ ] Set up HTTPS/TLS
+- [ ] Configure CORS for your clients
+- [ ] Enable rate limiting
+- [ ] Set appropriate session timeouts
+- [ ] Test authentication flow end-to-end
+- [ ] Monitor authentication logs
+- [ ] Document API keys/tokens for clients