@realtimex/email-automator 2.1.0

package/.env.example

@@ -0,0 +1,35 @@
+# Supabase Configuration
+VITE_SUPABASE_URL=your_supabase_url
+VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
+
+# API Configuration
+# Express API URL (default: http://localhost:3004)
+# Note: RealTimeX Desktop uses ports 3001/3002
+VITE_API_URL=http://localhost:3004
+PORT=3004
+
+# OpenAI / LLM Configuration
+LLM_API_KEY=your_llm_api_key
+LLM_BASE_URL=https://api.openai.com/v1
+LLM_MODEL=gpt-4o-mini
+
+# Security (required in production)
+JWT_SECRET="your-secure-jwt-secret-min-32-chars"
+TOKEN_ENCRYPTION_KEY="your-32-character-encryption-key"
+CORS_ORIGINS="https://yourdomain.com"
+
+# Development Only - Bypass authentication (DO NOT use in production)
+DISABLE_AUTH=true
+
+# Gmail OAuth
+GMAIL_CLIENT_ID=your_gmail_client_id
+GMAIL_CLIENT_SECRET=your_gmail_client_secret
+
+# Microsoft Graph (Outlook)
+MS_GRAPH_CLIENT_ID=your_ms_graph_client_id
+MS_GRAPH_TENANT_ID=common
+MS_GRAPH_CLIENT_SECRET=your_ms_graph_client_secret
+
+# Processing
+EMAIL_BATCH_SIZE=20
+SYNC_INTERVAL_MS=300000

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RealTimeX Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,247 @@
+# AI Email Automator v2.0
+
+An agentic, AI-powered email management platform that learns to handle your inbox. Categorize, archive, delete, and draft responses automatically using LLMs and Supabase.
+
+## 🚀 Vision: "Own Your Inbox"
+
+The AI Email Automator is designed as a standalone "Agent" for the RealTimeX ecosystem. It follows the **Own Your Data** philosophy:
+
+- **Zero Cloud Costs**: Runs on your infrastructure using Supabase
+- **Privacy First**: Your emails are processed on your private infrastructure
+- **Agentic Intelligence**: An assistant that suggests "Winning Responses"
+- **Production Ready**: Full security, testing, and DevOps infrastructure
+
+## ✨ Features
+
+### Core Capabilities
+- **Smart Categorization**: AI classifies emails (Spam, Newsletter, Support, Client, etc.)
+- **Inbox Zero Engine**: Auto-trash spam and archive newsletters
+- **Winning Responses**: AI-generated draft replies for important emails
+- **Multi-Provider**: Gmail (OAuth2) and Microsoft 365 (Device Flow)
+- **Automation Rules**: Custom rules for auto-pilot email handling
+- **Real-time Sync**: Live updates via Supabase subscriptions
+- **Background Scheduler**: Automatic periodic email sync
+
+### Production Features
+- **Security**: JWT auth, token encryption, rate limiting, input validation
+- **Hybrid Architecture**: Edge Functions (serverless) + Local App (privacy)
+- **State Management**: React Context with centralized app state
+- **Error Handling**: Error boundaries, toast notifications, logging
+- **Analytics Dashboard**: Email stats, category breakdown, sync history
+- **RealTimeX Integration**: Works with RealTimeX Desktop as Local App
+
+## 🛠 Tech Stack
+
+| Layer | Technologies |
+|-------|-------------|
+| **Frontend** | React 19, Vite 7, TailwindCSS 4, Lucide Icons |
+| **Edge Functions** | Deno, Supabase Functions (OAuth, DB proxy) |
+| **Local API** | Node.js, Express 5, TypeScript (Sync, AI) |
+| **AI** | OpenAI / Instructor-JS (supports Ollama, LM Studio) |
+| **Database** | Supabase (PostgreSQL) with RLS |
+| **Testing** | Vitest, Testing Library |
+
+## 🏁 Quick Start
+
+For detailed instructions on installation, configuration, and usage, please see the [**Email Automator Documentation Hub**](docs/README.md).
+
+### Prerequisites
+- Node.js v20+
+- Supabase project with CLI access
+- LLM API key (OpenAI, Anthropic, or local)
+
+### Option 1: Using npx (Recommended)
+
+```bash
+# Interactive setup
+npx @realtimex/email-automator-setup
+
+# Deploy Edge Functions
+npx @realtimex/email-automator-deploy
+
+# Start Email Automator
+npx @realtimex/email-automator
+```
+
+### Option 2: Clone and Install
+
+```bash
+git clone https://github.com/therealtimex/email-automator.git
+cd email-automator
+npm install
+```
+
+### Setup
+
+1. **Deploy Edge Functions to Supabase:**
+```bash
+supabase login
+./scripts/deploy-functions.sh
+```
+
+2. **Configure Edge Function Secrets in Supabase Dashboard:**
+   - Settings → Edge Functions → Add secrets
+   - Required: `TOKEN_ENCRYPTION_KEY`, `GMAIL_CLIENT_ID`, `GMAIL_CLIENT_SECRET`, etc.
+
+3. **Configure Local Environment:**
+```bash
+cp .env.example .env
+# Edit .env with your credentials
+```
+
+### Development
+
+```bash
+# Terminal 1: Local API (Email Sync & AI Processing)
+# Default port: 3004 (RealTimeX Desktop uses 3001/3002)
+npm run dev:api
+
+# Terminal 2: Frontend
+npm run dev
+
+# Optional: Specify custom ports
+npm run dev:api -- --port 3005
+npm run dev -- --port 5174
+```
+
+**Note:** Email Automator uses port **3004** by default to avoid conflicts with RealTimeX Desktop (ports 3001/3002). You can change ports via command line arguments or environment variables.
+
+### Using npx
+
+```bash
+# Start with default port (3004)
+npx @realtimex/email-automator
+
+# Start with custom port
+npx @realtimex/email-automator --port 3005
+```
+
+See [NPX Usage Guide](docs-dev/NPX-USAGE.md) for complete documentation.
+
+## 📂 Project Structure
+
+```
+├── api/                       # Local App (Express)
+│   ├── server.ts              # Express entry point
+│   └── src/
+│       ├── routes/            # Sync & Actions endpoints
+│       ├── services/          # Email sync, AI processing
+│       └── utils/             # Logger, crypto, helpers
+├── src/                       # Frontend (React)
+│   ├── components/            # React components
+│   ├── context/               # App state management
+│   ├── hooks/                 # Custom hooks (realtime)
+│   └── lib/                   # Hybrid API client, types
+├── supabase/                  # Supabase Configuration
+│   ├── functions/             # Edge Functions (OAuth, DB)
+│   │   ├── _shared/           # Shared utilities
+│   │   ├── auth-gmail/        # Gmail OAuth
+│   │   ├── auth-microsoft/    # Microsoft OAuth
+│   │   ├── api-v1-accounts/   # Account management
+│   │   ├── api-v1-emails/     # Email operations
+│   │   ├── api-v1-rules/      # Rules CRUD
+│   │   └── api-v1-settings/   # Settings & stats
+│   └── migrations/            # Database schema
+├── scripts/
+│   └── deploy-functions.sh    # Deploy Edge Functions
+└── tests/                     # Unit & integration tests
+```
+
+## 🔐 Environment Variables
+
+### Edge Functions (Supabase Dashboard)
+```bash
+TOKEN_ENCRYPTION_KEY=32-char-key
+GMAIL_CLIENT_ID=xxx
+GMAIL_CLIENT_SECRET=xxx
+MS_GRAPH_CLIENT_ID=xxx
+MS_GRAPH_CLIENT_SECRET=xxx
+```
+
+### Local App (.env file)
+```bash
+# Supabase
+VITE_SUPABASE_URL=https://xxx.supabase.co
+VITE_SUPABASE_ANON_KEY=your-anon-key
+
+# API Configuration (default port: 3004)
+VITE_API_URL=http://localhost:3004
+PORT=3004
+
+# LLM
+LLM_API_KEY=your-llm-key
+LLM_BASE_URL=https://api.openai.com/v1
+LLM_MODEL=gpt-4o-mini
+
+# Development
+DISABLE_AUTH=true
+```
+
+## 🧪 Testing
+
+```bash
+npm run test           # Watch mode
+npm run test:run       # Single run
+npm run test:coverage  # With coverage
+```
+
+## 📡 API Architecture
+
+### Edge Functions (Supabase)
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/auth-gmail?action=url` | Get Gmail OAuth URL |
+| POST | `/auth-gmail` | Complete Gmail OAuth |
+| POST | `/auth-microsoft?action=device-flow` | Start Microsoft device flow |
+| GET | `/api-v1-accounts` | List connected accounts |
+| GET | `/api-v1-emails` | List processed emails |
+| GET | `/api-v1-rules` | List automation rules |
+| GET | `/api-v1-settings` | Get user settings |
+
+### Local App (Express)
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/sync` | Trigger email sync |
+| POST | `/api/actions/execute` | Execute email action |
+| POST | `/api/actions/draft/:id` | Generate draft reply |
+| GET | `/api/health` | Health check |
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests: `npm run test:run`
+5. Submit a Pull Request
+
+## 📄 License
+
+MIT License - Copyright (c) 2026 RealTimeX Team
+
+## 📦 NPX Commands
+
+Email Automator is fully compatible with npx for easy installation and execution:
+
+| Command | Description |
+|---------|-------------|
+| `npx @realtimex/email-automator` | Start the Email Automator API server |
+| `npx @realtimex/email-automator-setup` | Interactive setup wizard |
+| `npx @realtimex/email-automator-deploy` | Deploy Edge Functions to Supabase |
+
+### Examples
+
+```bash
+# First time setup
+npx @realtimex/email-automator-setup
+npx @realtimex/email-automator-deploy
+npx @realtimex/email-automator
+
+# Daily usage
+npx @realtimex/email-automator
+
+# Custom port
+npx @realtimex/email-automator --port 3005
+```
+
+See [NPX Usage Guide](docs-dev/NPX-USAGE.md) for complete documentation.
+

package/api/server.ts

@@ -0,0 +1,130 @@
+import express from 'express';
+import cors from 'cors';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { spawn } from 'child_process';
+import { config, validateConfig } from './src/config/index.js';
+import { errorHandler } from './src/middleware/errorHandler.js';
+import { apiRateLimit } from './src/middleware/rateLimit.js';
+import routes from './src/routes/index.js';
+import { logger } from './src/utils/logger.js';
+import { getServerSupabase } from './src/services/supabase.js';
+import { startScheduler, stopScheduler } from './src/services/scheduler.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Validate configuration
+const configValidation = validateConfig();
+if (!configValidation.valid) {
+    logger.warn('Configuration warnings', { errors: configValidation.errors });
+}
+
+const app = express();
+
+// Security headers
+app.use((req, res, next) => {
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('X-Frame-Options', 'DENY');
+    res.setHeader('X-XSS-Protection', '1; mode=block');
+    if (config.isProduction) {
+        res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
+    }
+    next();
+});
+
+// CORS configuration
+app.use(cors({
+    origin: config.isProduction 
+        ? config.security.corsOrigins 
+        : true, // Allow all in development
+    credentials: true,
+    methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+    allowedHeaders: ['Content-Type', 'Authorization', 'X-Supabase-Url', 'X-Supabase-Anon-Key'],
+}));
+
+// Body parsing
+app.use(express.json({ limit: '10mb' }));
+app.use(express.urlencoded({ extended: true, limit: '10mb' }));
+
+// Request logging
+app.use((req, res, next) => {
+    const start = Date.now();
+    res.on('finish', () => {
+        const duration = Date.now() - start;
+        logger.debug(`${req.method} ${req.path}`, {
+            status: res.statusCode,
+            duration: `${duration}ms`,
+        });
+    });
+    next();
+});
+
+// Rate limiting (global)
+app.use('/api', apiRateLimit);
+
+// API routes
+app.use('/api', routes);
+
+// Serve static files in production or if dist exists
+const distPath = path.join(__dirname, '..', 'dist');
+app.use(express.static(distPath));
+
+// Handle client-side routing
+app.get(/.*/, (req, res, next) => {
+    if (req.path.startsWith('/api')) return next();
+    res.sendFile(path.join(distPath, 'index.html'), (err) => {
+        if (err) {
+            // If dist doesn't exist, return 404 for non-API routes
+            res.status(404).json({ 
+                success: false, 
+                error: { code: 'NOT_FOUND', message: 'Frontend not built or endpoint not found' } 
+            });
+        }
+    });
+});
+
+// Error handler (must be last)
+app.use(errorHandler);
+
+// Graceful shutdown
+const shutdown = () => {
+    logger.info('Shutting down gracefully...');
+    stopScheduler();
+    process.exit(0);
+};
+
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
+
+// Start server
+const server = app.listen(config.port, () => {
+    const url = `http://localhost:${config.port}`;
+    logger.info(`Server running at ${url}`, {
+        environment: config.nodeEnv,
+        supabase: getServerSupabase() ? 'connected' : 'not configured',
+    });
+    
+    // Start background scheduler
+    if (getServerSupabase()) {
+        startScheduler();
+    }
+
+    // Automatically open browser unless -n flag is provided
+    if (!config.noUi) {
+        const startCommand = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+        spawn(startCommand, [url], { detached: true }).unref();
+    }
+});
+
+// Handle server errors
+server.on('error', (error: NodeJS.ErrnoException) => {
+    if (error.code === 'EADDRINUSE') {
+        logger.error(`Port ${config.port} is already in use`);
+    } else {
+        logger.error('Server error', error);
+    }
+    process.exit(1);
+});
+
+export default app;

package/api/src/config/index.ts

@@ -0,0 +1,102 @@
+import dotenv from 'dotenv';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+dotenv.config();
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function parseArgs(args: string[]): { port: number | null, noUi: boolean } {
+    const portIndex = args.indexOf('--port');
+    let port = null;
+    if (portIndex !== -1 && args[portIndex + 1]) {
+        const p = parseInt(args[portIndex + 1], 10);
+        if (!isNaN(p) && p > 0 && p < 65536) {
+            port = p;
+        }
+    }
+    
+    const noUi = args.includes('--no-ui');
+    
+    return { port, noUi };
+}
+
+const cliArgs = parseArgs(process.argv.slice(2));
+
+export const config = {
+    // Server
+    // Default port 3004 (RealTimeX Desktop uses 3001/3002)
+    port: cliArgs.port || (process.env.PORT ? parseInt(process.env.PORT, 10) : 3004),
+    noUi: cliArgs.noUi,
+    nodeEnv: process.env.NODE_ENV || 'development',
+    isProduction: process.env.NODE_ENV === 'production',
+
+    // Paths
+    rootDir: join(__dirname, '..', '..', '..'),
+    scriptsDir: join(__dirname, '..', '..', '..', 'scripts'),
+
+    // Supabase
+    supabase: {
+        url: process.env.SUPABASE_URL || process.env.VITE_SUPABASE_URL || '',
+        anonKey: process.env.SUPABASE_ANON_KEY || process.env.VITE_SUPABASE_ANON_KEY || '',
+        serviceRoleKey: process.env.SUPABASE_SERVICE_ROLE_KEY || '',
+    },
+
+    // LLM
+    llm: {
+        apiKey: process.env.LLM_API_KEY || '',
+        baseUrl: process.env.LLM_BASE_URL,
+        model: process.env.LLM_MODEL || 'gpt-4o-mini',
+    },
+
+    // OAuth - Gmail
+    gmail: {
+        clientId: process.env.GMAIL_CLIENT_ID || '',
+        clientSecret: process.env.GMAIL_CLIENT_SECRET || '',
+        redirectUri: process.env.GMAIL_REDIRECT_URI || 'urn:ietf:wg:oauth:2.0:oob',
+    },
+
+    // OAuth - Microsoft
+    microsoft: {
+        clientId: process.env.MS_GRAPH_CLIENT_ID || '',
+        tenantId: process.env.MS_GRAPH_TENANT_ID || 'common',
+        clientSecret: process.env.MS_GRAPH_CLIENT_SECRET || '',
+    },
+
+    // Security
+    security: {
+        encryptionKey: process.env.TOKEN_ENCRYPTION_KEY || '',
+        jwtSecret: process.env.JWT_SECRET || 'dev-secret-change-in-production',
+        corsOrigins: process.env.CORS_ORIGINS?.split(',') || ['http://localhost:3003', 'http://localhost:5173'],
+        rateLimitWindowMs: 15 * 60 * 1000, // 15 minutes
+        rateLimitMax: 100,
+        disableAuth: process.env.DISABLE_AUTH === 'true',
+    },
+
+    // Processing
+    processing: {
+        batchSize: parseInt(process.env.EMAIL_BATCH_SIZE || '20', 10),
+        syncIntervalMs: parseInt(process.env.SYNC_INTERVAL_MS || '60000', 10), // 1 minute
+        maxRetries: 3,
+    },
+};
+
+export function validateConfig(): { valid: boolean; errors: string[] } {
+    const errors: string[] = [];
+
+    if (!config.supabase.url) {
+        errors.push('SUPABASE_URL is required');
+    }
+    if (!config.supabase.anonKey) {
+        errors.push('SUPABASE_ANON_KEY is required');
+    }
+    if (config.isProduction && config.security.jwtSecret === 'dev-secret-change-in-production') {
+        errors.push('JWT_SECRET must be set in production');
+    }
+    if (config.isProduction && !config.security.encryptionKey) {
+        errors.push('TOKEN_ENCRYPTION_KEY must be set in production');
+    }
+
+    return { valid: errors.length === 0, errors };
+}

package/api/src/middleware/auth.ts

@@ -0,0 +1,166 @@
+import { Request, Response, NextFunction } from 'express';
+import { createClient, SupabaseClient, User } from '@supabase/supabase-js';
+import { config } from '../config/index.js';
+import { AuthenticationError, AuthorizationError } from './errorHandler.js';
+import { createLogger, Logger } from '../utils/logger.js';
+
+const logger = createLogger('AuthMiddleware');
+
+import { getServerSupabase, isValidUrl } from '../services/supabase.js';
+
+// Extend Express Request to include user
+declare global {
+    namespace Express {
+        interface Request {
+            user?: User;
+            supabase?: SupabaseClient;
+        }
+    }
+}
+
+// Check if anon key looks valid (JWT or publishable key format)
+function isValidAnonKey(key: string): boolean {
+    if (!key) return false;
+    // JWT anon keys start with eyJ, publishable keys start with sb_publishable_
+    return key.startsWith('eyJ') || key.startsWith('sb_publishable_');
+}
+
+// Helper to get Supabase config from request headers (frontend passes these)
+function getSupabaseConfigFromRequest(req: Request): { url: string; anonKey: string } | null {
+    const url = req.headers['x-supabase-url'] as string;
+    const anonKey = req.headers['x-supabase-anon-key'] as string;
+
+    if (url && anonKey && isValidUrl(url) && isValidAnonKey(anonKey)) {
+        return { url, anonKey };
+    }
+    return null;
+}
+
+export async function authMiddleware(
+    req: Request,
+    _res: Response,
+    next: NextFunction
+): Promise<void> {
+    try {
+        // Get Supabase config: prefer env vars, fallback to request headers
+        const headerConfig = getSupabaseConfigFromRequest(req);
+        
+        const envUrl = config.supabase.url;
+        const envKey = config.supabase.anonKey;
+
+        // Basic validation: URL must start with http(s)
+        // This prevents using placeholders like "CHANGE_ME" or empty strings
+        const isEnvUrlValid = envUrl && (envUrl.startsWith('http://') || envUrl.startsWith('https://'));
+        const isEnvKeyValid = !!envKey && envKey.length > 0;
+        
+        const supabaseUrl = isEnvUrlValid ? envUrl : (headerConfig?.url || '');
+        const supabaseAnonKey = isEnvKeyValid ? envKey : (headerConfig?.anonKey || '');
+
+        // Development bypass: skip auth if DISABLE_AUTH=true in non-production
+        if (config.security.disableAuth && !config.isProduction) {
+            logger.warn('Auth disabled for development - creating mock user');
+
+            // Create a mock user for development
+            req.user = {
+                id: '00000000-0000-0000-0000-000000000000',
+                email: 'dev@local.test',
+                user_metadata: {},
+                app_metadata: {},
+                aud: 'authenticated',
+                created_at: new Date().toISOString(),
+            } as User;
+
+            // Use the shared Supabase client, or create one from request headers
+            let supabase = getServerSupabase();
+            if (!supabase && supabaseUrl && supabaseAnonKey) {
+                supabase = createClient(supabaseUrl, supabaseAnonKey, {
+                    auth: { autoRefreshToken: false, persistSession: false },
+                });
+            }
+
+            if (supabase) {
+                req.supabase = supabase;
+                // Initialize logger persistence for mock user
+                Logger.setPersistence(supabase, req.user.id);
+            } else {
+                throw new AuthenticationError('Supabase not configured. Please set up Supabase in the app or provide SUPABASE_URL/ANON_KEY in .env');
+            }
+
+            return next();
+        }
+
+        const authHeader = req.headers.authorization;
+
+        if (!authHeader?.startsWith('Bearer ')) {
+            throw new AuthenticationError('Missing or invalid authorization header');
+        }
+
+        const token = authHeader.substring(7);
+
+        if (!supabaseUrl || !supabaseAnonKey) {
+            throw new AuthenticationError('Supabase not configured. Please set up Supabase in the app or provide SUPABASE_URL/ANON_KEY in .env');
+        }
+
+        // Create a Supabase client with the user's token
+        const supabase = createClient(supabaseUrl, supabaseAnonKey, {
+            global: {
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                },
+            },
+        });
+
+        // Verify the token by getting the user
+        const { data: { user }, error } = await supabase.auth.getUser(token);
+
+        if (error || !user) {
+            logger.debug('Auth failed', { error: error?.message });
+            throw new AuthenticationError('Invalid or expired token');
+        }
+
+        // Initialize logger persistence for this request
+        Logger.setPersistence(supabase, user.id);
+
+        // Attach user and supabase client to request
+        req.user = user;
+        req.supabase = supabase;
+
+        next();
+    } catch (error) {
+        logger.error('Auth middleware error', error);
+        next(error);
+    }
+}
+
+export function optionalAuth(
+    req: Request,
+    _res: Response,
+    next: NextFunction
+): void {
+    const authHeader = req.headers.authorization;
+
+    if (!authHeader?.startsWith('Bearer ')) {
+        // No auth provided, continue without user
+        return next();
+    }
+
+    // If auth is provided, validate it
+    authMiddleware(req, _res, next);
+}
+
+export function requireRole(roles: string[]) {
+    return async (req: Request, _res: Response, next: NextFunction) => {
+        if (!req.user) {
+            return next(new AuthenticationError());
+        }
+
+        // Check user metadata for role (customize based on your auth setup)
+        const userRole = req.user.user_metadata?.role || 'user';
+
+        if (!roles.includes(userRole)) {
+            return next(new AuthorizationError(`Requires one of: ${roles.join(', ')}`));
+        }
+
+        next();
+    };
+}