PSA/docs/email/email_registration_system.md

Email Registration System Documentation

Overview

The email registration system allows clients to self-register using their company email addresses. The system supports two registration flows:

1. Contact-based registration (existing functionality)
   • Allows existing contacts to create user accounts
   • Automatically assigns client role
   • Validates contact status (active/inactive)
   • Preserves existing company and contact relationships
2. Email suffix-based registration (new functionality)
   • Validates email domain against allowed suffixes
   • Creates new contact and user records
   • Assigns roles based on company context (first user gets client_admin)

Architecture

Database Tables

1. company_email_settings

   • Stores allowed email suffixes for each company
   • Reference table in CitusDB environment
   • Includes self-registration toggle per suffix

2. pending_registrations

   • Tracks registration attempts and their status
   • Distributed table in CitusDB environment
   • Statuses: PENDING_VERIFICATION, VERIFIED, COMPLETED, EXPIRED

3. verification_tokens

   • Manages email verification tokens
   • Reference table in CitusDB environment
   • Includes expiration and usage tracking

Security Measures

1. Rate Limiting

   • Registration attempts: 5 per hour per email
   • Verification attempts: 3 per 5 minutes per token
   • Email sending: 3 per hour per email
   • Includes user-friendly error messages with wait times
   • Memory-based implementation using rate-limiter-flexible

2. Token Security

   • 32-byte random tokens using crypto library
   • Base64URL encoding for URL safety
   • 24-hour expiration
   • One-time use only
   • Validation includes expiration and usage checks
   • Transaction-based token management

3. Audit Logging

   • Security event logging temporarily disabled (tenant context issue)
   • Will log registration attempts, verifications, and completions
   • Includes detailed event context and tenant isolation
   • Uses centralized audit logging system

Registration Flow

1. User submits registration form

   • Validates rate limits for registration attempts
   • For contacts:
     • Verifies contact exists and is active
     • Checks for existing user account
     • Creates user with contact association
   • For email suffix:
     • Validates email domain against allowed suffixes
     • Determines company from email suffix
     • Creates pending registration with expiration
     • Generates and stores verification token
     • Validates email sending rate limit
     • Sends verification email using templated system

2. User verifies email

   • Clicks link in email with token and registration ID
   • System validates token:
     • Checks rate limits for verification attempts
     • Verifies token exists and hasn't been used
     • Confirms token hasn't expired
     • Validates registration status is PENDING_VERIFICATION
   • Updates token usage timestamp
   • Updates registration status to VERIFIED

3. System completes registration

   • Validates registration exists and is verified
   • Executes in a database transaction:
     • Creates contact record if needed
     • Creates user account
     • Assigns client role to user (client_admin role is managed separately through settings)
     • Updates registration status to COMPLETED
   • Handles rollback on any failure

Maintenance

Cleanup Jobs

Two cleanup jobs run hourly:

1. cleanupExpiredRegistrations

   • Finds registrations past 24-hour expiration
   • Updates status to EXPIRED
   • Logs cleanup events
   • Maintains registration record for audit purposes

2. cleanupExpiredTokens

   • Removes expired verification tokens
   • Only removes tokens that were never used
   • Preserves used tokens for audit trail
   • Runs after registration cleanup

Monitoring

Monitor these aspects:

1. Registration Attempts

   • Watch for unusual patterns
   • Track success/failure rates
   • Monitor rate limit hits

2. Token Usage

   • Track verification success rates
   • Monitor token expiration patterns
   • Watch for repeated failures

3. Email Delivery

   • Monitor sending success rates
   • Track delivery delays
   • Watch for bounces

Troubleshooting

Common issues and solutions:

1. Rate Limit Exceeded

   • System provides specific wait time in error message
   • Check logs for abuse patterns
   • Verify limit configurations in rate-limiter-flexible settings
   • Consider adjusting points or duration if needed

2. Token Verification Failures

   • Check token expiration (24-hour limit)
   • Verify email delivery through email service logs
   • Look for multiple verification attempts
   • Check if token was already used
   • Validate registration ID matches token

3. Role Assignment Issues

   • Verify role existence in roles table
   • Check tenant isolation in all related tables
   • Validate company settings and email suffix configuration
   • Verify first-user detection logic

Administration

Administration Interface

The system provides two main administration interfaces:

1. Email Registration Settings

   • Email Suffix Management:
     • Add new email suffixes with validation
     • Delete existing suffixes
     • View all configured suffixes in a data table
     • Case-insensitive suffix handling (automatically converted to lowercase)
   • Registration Controls:
     • Toggle self-registration per suffix using switches
     • Immediate effect on registration availability
     • Visual feedback for configuration status
     • Error handling for failed operations
   • User Interface Features:
     • Clean, card-based layout
     • Interactive data table for suffix management
     • Dropdown menus for suffix actions
     • Form validation and error messaging
     • Loading states during operations
   • Error Handling:
     • Displays error alerts for failed operations
     • Validates input before submission
     • Maintains state consistency after errors
     • Provides feedback for all user actions

2. User Management

   • Role Management:
     • View and edit user roles through user details drawer
     • Assign/remove client_admin role as needed
     • Manage role-based permissions
     • Maintain audit trail of role changes
   • User Controls:
     • Edit user details and status
     • Reset passwords (admin only)
     • Enable/disable user accounts
     • View user activity and roles

Security Settings

Available controls:

• Rate limit configurations
• Token expiration times
• Email sending limits
• IP-based restrictions

Best Practices

1. Email Suffixes

   • Use specific suffixes when possible
   • Avoid common email providers
   • Regularly review and update

2. Security

   • Monitor audit logs regularly
   • Review rate limits periodically
   • Keep email templates updated

3. Maintenance

   • Check cleanup job logs
   • Monitor database size
   • Review expired registrations

Deployment

Prerequisites

• PostgreSQL or CitusDB
• Node.js environment
• Email service configuration

Configuration Steps

1. Run database migrations
2. Configure email service
3. Set environment variables
4. Enable cleanup jobs

Rollback Procedures

1. Disable new registrations
2. Revert database migrations
3. Remove email settings

Troubleshooting Guide

Common Issues

1. Registration Fails

   • Check email suffix configuration
   • Verify rate limits
   • Check database connectivity

2. Verification Link Invalid

   • Check token expiration
   • Verify token usage
   • Check email delivery logs

3. Role Assignment Fails

   • Verify role existence
   • Check tenant configuration
   • Validate company settings

Monitoring Checklist

Daily:

• Check registration success rates
• Monitor verification attempts
• Review security logs

Weekly:

• Analyze rate limit patterns
• Check cleanup job effectiveness
• Review expired registrations

Monthly:

• Audit email suffix configurations
• Review security settings
• Check system performance

Support

For issues:

1. Check audit logs first
2. Review rate limit status
3. Verify email delivery
4. Check database consistency

Future Improvements

Planned enhancements:

1. Enhanced rate limiting
2. IP-based restrictions
3. Improved monitoring
4. Additional security measures