# MonacoUSA Portal - Integration Review & Troubleshooting Guide

## SMTP Email Integration Points

### 1. Email Configuration Storage
- **Location**: `server/utils/admin-config.ts`
- **Storage**: Encrypted in `/app/data/admin-config.json` (Docker) or `./data/admin-config.json` (local)
- **Fields**: host, port, secure, username, password, fromAddress, fromName

### 2. Email Service Implementation
- **Location**: `server/utils/email.ts`
- **Features**:
  - Auto-detects security settings based on port
  - Increased timeouts (60 seconds) for slow servers
  - Supports STARTTLS (port 587) and SSL/TLS (port 465)
  - Authentication type set to 'login' for compatibility
  - Accepts self-signed certificates

### 3. Email Usage Points
- **Registration**: `server/api/registration.post.ts` - Sends welcome email with verification link
- **Portal Account Creation**: `server/api/members/[id]/create-portal-account.post.ts` - Sends welcome email
- **Password Reset**: `server/api/auth/forgot-password.post.ts` - Sends password reset link
- **Email Verification Resend**: `server/api/auth/send-verification-email.post.ts`
- **Test Email**: `server/api/admin/test-email.post.ts` - Admin panel test

### 4. Common SMTP Issues & Solutions

#### Issue: "500 plugin timeout" / EAUTH errors
**Solutions**:
1. **Port 587 (STARTTLS)**:
   - Set SSL/TLS: OFF
   - Username: Full email address (noreply@monacousa.org)
   - Password: Your SMTP password (not email password if different)

2. **Port 465 (SSL/TLS)**:
   - Set SSL/TLS: ON
   - Same credentials as above

3. **Port 25 (Unencrypted)**:
   - Set SSL/TLS: OFF
   - May not require authentication
   - Not recommended for production

4. **Alternative Configuration** for mail.monacousa.org:
   - Try port 587 with SSL/TLS OFF
   - Try port 465 with SSL/TLS ON
   - Ensure username is full email address
   - Some servers require app-specific passwords

#### Issue: Connection timeouts
**Solutions**:
- Timeouts already increased to 60 seconds
- Check firewall rules allow outbound connections on SMTP port
- Verify DNS resolution of mail server

#### Issue: Certificate errors
**Solutions**:
- Self-signed certificates are already accepted
- TLS minimum version set to TLSv1 for compatibility

### 5. Testing SMTP Without Email
If SMTP cannot be configured, the system gracefully handles email failures:
- Portal accounts are still created
- Users can use "Forgot Password" to set initial password
- Admin sees appropriate messages about email status

## Keycloak Integration Points

### 1. Authentication Flow
- **Login**: `server/api/auth/keycloak/login.get.ts` - Redirects to Keycloak
- **Callback**: `server/api/auth/keycloak/callback.get.ts` - Handles OAuth callback
- **Session**: `server/utils/session.ts` - Manages encrypted sessions
- **Logout**: `server/api/auth/logout.post.ts` - Clears session and Keycloak logout

### 2. User Management
- **Admin Client**: `server/utils/keycloak-admin.ts`
- **Features**:
  - Create users with role-based registration
  - Update user attributes (membership data)
  - Password reset functionality
  - Email verification tokens
  - User search by email

### 3. Role-Based Access
- **Tiers**: admin, board, user
- **Middleware**:
  - `middleware/auth.ts` - General authentication
  - `middleware/auth-admin.ts` - Admin only
  - `middleware/auth-board.ts` - Board and admin
  - `middleware/auth-user.ts` - All authenticated users

### 4. Member-Portal Sync
- **Dual Database System**:
  - NocoDB: Member records (source of truth)
  - Keycloak: Authentication and portal accounts
- **Sync Points**:
  - Registration creates both records
  - Portal account creation links existing member to Keycloak
  - Member updates sync to Keycloak attributes

### 5. Common Keycloak Issues & Solutions

#### Issue: Login redirect loops
**Solutions**:
- Check `NUXT_KEYCLOAK_CALLBACK_URL` matches actual domain
- Verify Keycloak client redirect URIs include callback URL
- Ensure session secret is set and consistent

#### Issue: User creation failures
**Solutions**:
- Check Keycloak admin credentials in environment
- Verify realm exists and is accessible
- Ensure email is unique in Keycloak

#### Issue: Role assignment not working
**Solutions**:
- Verify realm roles exist: user, board, admin
- Check client scope mappings include roles
- Ensure token includes role claims

## Environment Variables Required

### Keycloak Configuration
```env
NUXT_KEYCLOAK_ISSUER=https://auth.monacousa.org/realms/monacousa-portal
NUXT_KEYCLOAK_CLIENT_ID=monacousa-portal
NUXT_KEYCLOAK_CLIENT_SECRET=your-client-secret
NUXT_KEYCLOAK_CALLBACK_URL=https://monacousa.org/auth/callback
NUXT_KEYCLOAK_ADMIN_USERNAME=admin
NUXT_KEYCLOAK_ADMIN_PASSWORD=admin-password
```

### Session Security
```env
NUXT_SESSION_SECRET=48-character-secret-key
NUXT_ENCRYPTION_KEY=32-character-encryption-key
```

### Public Configuration
```env
NUXT_PUBLIC_DOMAIN=monacousa.org
```

## Health Check Endpoints

### System Health
- **Endpoint**: `GET /api/health`
- **Checks**:
  - Database connectivity (NocoDB)
  - Keycloak connectivity
  - Session management
  - File storage (if configured)

## Troubleshooting Workflow

### For SMTP Issues:
1. Try port 587 with SSL/TLS OFF first
2. If fails, try port 465 with SSL/TLS ON
3. Check credentials (use full email as username)
4. Test with personal Gmail/Outlook account to verify code works
5. Check firewall/network restrictions
6. Review server logs for specific error messages

### For Keycloak Issues:
1. Verify all environment variables are set
2. Check Keycloak server is accessible
3. Test with direct Keycloak login first
4. Review browser console for redirect issues
5. Check server logs for token/session errors
6. Verify realm and client configuration in Keycloak admin

## Manual SMTP Testing

To manually test SMTP settings without the portal:

### Using OpenSSL (for connection test):
```bash
# For STARTTLS (port 587)
openssl s_client -starttls smtp -connect mail.monacousa.org:587

# For SSL/TLS (port 465)
openssl s_client -connect mail.monacousa.org:465
```

### Using Telnet (for basic connectivity):
```bash
telnet mail.monacousa.org 587
```

### Using swaks (comprehensive SMTP test):
```bash
swaks --to test@example.com \
      --from noreply@monacousa.org \
      --server mail.monacousa.org:587 \
      --auth LOGIN \
      --auth-user noreply@monacousa.org \
      --auth-password yourpassword \
      --tls
```

## Alternative Email Solutions

If SMTP continues to fail:

### 1. Use Gmail with App Password:
- Enable 2FA on Gmail account
- Generate app-specific password
- Use smtp.gmail.com:587
- Username: your gmail address
- Password: app-specific password

### 2. Use SendGrid (Free tier available):
- Sign up at sendgrid.com
- Create API key
- Use smtp.sendgrid.net:587
- Username: apikey (literal string)
- Password: your API key

### 3. Use Local Mail Server (Development):
- Install MailHog or MailCatcher
- No authentication required
- Captures all emails locally
- Perfect for testing

## System Architecture

```
┌─────────────────┐     ┌──────────────┐     ┌─────────────┐
│                 │────▶│              │────▶│             │
│   Frontend      │     │   Nuxt API   │     │  Keycloak   │
│   (Vue/Vuetify) │◀────│   Routes     │◀────│   Server    │
│                 │     │              │     │             │
└─────────────────┘     └──────────────┘     └─────────────┘
                               │                     ▲
                               │                     │
                               ▼                     │
                        ┌──────────────┐             │
                        │              │             │
                        │    NocoDB    │─────────────┘
                        │   Database   │
                        │              │
                        └──────────────┘
                               │
                               ▼
                        ┌──────────────┐
                        │              │
                        │     SMTP     │
                        │    Server    │
                        │              │
                        └──────────────┘
```

## Production Checklist

- [ ] All environment variables set correctly
- [ ] SSL certificates valid and configured
- [ ] Keycloak realm and client configured
- [ ] NocoDB database accessible and configured
- [ ] SMTP credentials tested and working
- [ ] Session secrets are strong and unique
- [ ] Firewall rules allow necessary ports
- [ ] Backup strategy in place
- [ ] Monitoring and logging configured
- [ ] Health check endpoint monitored

## Support Resources

- **Keycloak Documentation**: https://www.keycloak.org/documentation
- **NocoDB Documentation**: https://docs.nocodb.com
- **Nodemailer Documentation**: https://nodemailer.com
- **Nuxt 3 Documentation**: https://nuxt.com

## Contact for Issues

If you continue to experience issues after following this guide:
1. Check server logs for detailed error messages
2. Test each component independently
3. Verify network connectivity and DNS resolution
4. Review firewall and security group rules
5. Consider using alternative email providers
