botserver/web/desktop/MULTI_USER_SYSTEM.md

Multi-User System Documentation

Overview

This document describes the multi-user authentication system that enables users to manage their email accounts, drive storage, and chat sessions with proper authentication.

Architecture

User Authentication Model

• Anonymous Access: Chat can work without authentication
• Authenticated Access: Email, Drive, and Tasks require user login
• User Accounts: Stored in users table with credentials
• Session Management: JWT tokens stored in user_login_tokens table

Database Schema

New Tables (Migration 6.0.6)

1. user_email_accounts

   • Stores user email account credentials (IMAP/SMTP)
   • Supports multiple accounts per user
   • Passwords encrypted (base64 for now, should use AES-256 in production)
   • Primary account flagging

2. email_drafts

   • Stores email drafts per user/account
   • Supports to/cc/bcc, subject, body, attachments

3. email_folders

   • Caches IMAP folder structure and counts
   • Tracks unread/total counts per folder

4. user_preferences

   • Stores user preferences (theme, notifications, etc.)
   • JSON-based flexible storage

5. user_login_tokens

   • Session token management
   • Tracks device, IP, expiration
   • Supports token revocation

API Endpoints

Email Account Management

GET  /api/email/accounts              - List user's email accounts
POST /api/email/accounts/add          - Add new email account
DELETE /api/email/accounts/{id}       - Delete email account

Email Operations

POST /api/email/list                  - List emails from account
POST /api/email/send                  - Send email
POST /api/email/draft                 - Save draft
GET  /api/email/folders/{account_id}  - List IMAP folders

Request/Response Examples

Add Email Account

POST /api/email/accounts/add
{
  "email": "user@gmail.com",
  "display_name": "John Doe",
  "imap_server": "imap.gmail.com",
  "imap_port": 993,
  "smtp_server": "smtp.gmail.com",
  "smtp_port": 587,
  "username": "user@gmail.com",
  "password": "app_password_here",
  "is_primary": true
}

List Emails

POST /api/email/list
{
  "account_id": "uuid-here",
  "folder": "INBOX",
  "limit": 50,
  "offset": 0
}

Send Email

POST /api/email/send
{
  "account_id": "uuid-here",
  "to": "recipient@example.com",
  "cc": "cc@example.com",
  "bcc": "bcc@example.com",
  "subject": "Test Email",
  "body": "Email body content",
  "is_html": false
}

Frontend Components

Account Management (account.html)

• Profile management
• Email account configuration
• Drive settings
• Security (password change, active sessions)

Features:

• Add/edit/delete email accounts
• Test IMAP/SMTP connections
• Set primary account
• Provider presets (Gmail, Outlook, Yahoo)

Mail Client (mail/mail.html, mail/mail.js)

• Multi-account support
• Folder navigation (Inbox, Sent, Drafts, etc.)
• Compose, reply, forward emails
• Real-time email loading from IMAP
• Read/unread tracking
• Email deletion

Drive (drive/drive.html, drive/drive.js)

• Already supports multi-user through bucket isolation
• Connected to MinIO/S3 backend
• File browser with upload/download
• Folder creation and navigation

Usage Flow

1. User Registration/Login (TODO)

// Register new user
POST /api/auth/register
{
  "username": "john",
  "email": "john@example.com",
  "password": "secure_password"
}

// Login
POST /api/auth/login
{
  "username": "john",
  "password": "secure_password"
}
// Returns: { token: "jwt_token", user_id: "uuid" }

2. Add Email Account

1. Navigate to Account Settings
2. Click "Email Accounts" tab
3. Click "Add Account"
4. Fill in IMAP/SMTP details
5. Test connection (optional)
6. Save

3. Use Mail Client

1. Navigate to Mail section
2. Select account (if multiple)
3. View emails from selected account
4. Compose/send emails using selected account

4. Drive Access

1. Navigate to Drive section
2. Files are automatically scoped to user
3. Upload/download/manage files

Security Considerations

Current Implementation

• Passwords stored with base64 encoding (TEMPORARY)
• Session tokens in database
• HTTPS recommended for production

Production Requirements

1. Encryption

   • Replace base64 with AES-256-GCM for password encryption
   • Use encryption key from environment variable
   • Rotate keys periodically

2. Authentication

   • Implement JWT token-based authentication
   • Add middleware to verify tokens on protected routes
   • Implement refresh tokens

3. Rate Limiting

   • Add rate limiting on login attempts
   • Rate limit email sending
   • Rate limit API calls per user

4. CSRF Protection

   • Implement CSRF tokens for state-changing operations
   • Use SameSite cookies

5. Input Validation

   • Validate all email addresses
   • Sanitize email content (prevent XSS)
   • Validate IMAP/SMTP server addresses

Configuration

Environment Variables

# Database
DATABASE_URL=postgresql://user:pass@localhost/botserver

# Email (global fallback)
EMAIL_IMAP_SERVER=imap.example.com
EMAIL_IMAP_PORT=993
EMAIL_SMTP_SERVER=smtp.example.com
EMAIL_SMTP_PORT=587
EMAIL_USERNAME=default@example.com
EMAIL_PASSWORD=password

# Drive
DRIVE_SERVER=minio:9000
DRIVE_ACCESSKEY=minioadmin
DRIVE_SECRET=minioadmin

# Server
SERVER_HOST=0.0.0.0
SERVER_PORT=8080

Email Provider Configuration

Gmail

• IMAP: imap.gmail.com:993
• SMTP: smtp.gmail.com:587
• Note: Enable "Less secure app access" or use App Password

Outlook/Office 365

• IMAP: outlook.office365.com:993
• SMTP: smtp.office365.com:587
• Note: Modern auth supported

Yahoo Mail

• IMAP: imap.mail.yahoo.com:993
• SMTP: smtp.mail.yahoo.com:587
• Note: Requires app-specific password

Custom IMAP/SMTP

• Supports any standard IMAP/SMTP server
• SSL/TLS on standard ports (993/587)

Testing

Manual Testing

1. Add email account through UI
2. Test connection
3. List emails (should see recent emails)
4. Send test email
5. Check sent folder
6. Save draft
7. Delete email

API Testing with cURL

# List accounts
curl http://localhost:8080/api/email/accounts

# Add account
curl -X POST http://localhost:8080/api/email/accounts/add \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@gmail.com",
    "imap_server": "imap.gmail.com",
    "imap_port": 993,
    "smtp_server": "smtp.gmail.com",
    "smtp_port": 587,
    "username": "test@gmail.com",
    "password": "app_password",
    "is_primary": true
  }'

# List emails
curl -X POST http://localhost:8080/api/email/list \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "account-uuid-here",
    "folder": "INBOX",
    "limit": 10
  }'

Migration

Running Migrations

# Run new migration
diesel migration run

# Rollback if needed
diesel migration revert

Migration Status

• ✅ 6.0.0 - Initial schema (users, bots, sessions)
• ✅ 6.0.1 - Bot memories
• ✅ 6.0.2 - KB tools
• ✅ 6.0.3 - KB session tables
• ✅ 6.0.4 - Config management
• ✅ 6.0.5 - Automation updates
• ✅ 6.0.6 - User accounts (email, preferences, tokens) NEW

TODO - Future Enhancements

Authentication System

• Implement JWT token generation
• Add login/logout endpoints
• Add registration endpoint with email verification
• Add password reset flow
• Implement OAuth2 (Google, Microsoft, etc.)

Email Features

• Attachment support (upload/download)
• HTML email composition
• Email search
• Filters and labels
• Email threading/conversations
• Push notifications for new emails

Security

• Replace base64 with proper encryption (AES-256)
• Add 2FA support
• Implement rate limiting
• Add audit logging
• Session timeout handling

Drive Features

• Per-user storage quotas
• File sharing with permissions
• File versioning
• Trash/restore functionality
• Search across files

UI/UX

• Better error messages
• Loading states
• Progress indicators for uploads
• Drag and drop file upload
• Email preview without opening
• Keyboard shortcuts

Troubleshooting

Common Issues

1. Cannot connect to IMAP server

   • Check firewall rules
   • Verify IMAP server address and port
   • Ensure SSL/TLS is supported
   • Check if "less secure apps" is enabled (Gmail)

2. Email sending fails

   • Verify SMTP credentials
   • Check SMTP port (587 for STARTTLS, 465 for SSL)
   • Some providers require app-specific passwords

3. Password encryption errors

   • Ensure base64 encoding/decoding is working
   • Plan migration to proper encryption

4. No emails loading

   • Check if account is active
   • Verify IMAP folder name (case-sensitive)
   • Check database for account record

Contributing

When adding features to the multi-user system:

1. Update database schema with migrations
2. Add corresponding Diesel table definitions
3. Implement backend API endpoints
4. Update frontend components
5. Add to this documentation
6. Test with multiple users
7. Consider security implications

License

Same as BotServer - AGPL-3.0