feat: Restrict account creation to users from specific organizations or domains

[cc8t]

Introduction

This feature adds the ability to restrict user registration to specific email domains when registration is enabled. Currently, when DISALLOW_REGISTRATION is set to false, any user with any email address can register. This feature will allow administrators to configure a whitelist of allowed email domains, ensuring that only users with email addresses from approved domains can create accounts.

Glossary

• System: The Kutt URL shortener application
• Administrator: A user with admin privileges who configures the system
• Registration: The process by which a new user creates an account
• Email Domain: The portion of an email address after the @ symbol (e.g., "company.com" in "user@company.com")
• Domain Whitelist: A configurable list of allowed email domains for registration
• Verification Email: An email sent to new users to verify their email address

Requirements

Requirement 1

User Story: As an administrator, I want to configure allowed email domains for registration, so that I can restrict account creation to users from specific organizations or domains.

Acceptance Criteria

1. WHEN the administrator sets the REGISTRATION_ALLOWED_DOMAINS environment variable THEN the System SHALL parse it as a comma-separated list of allowed email domains
2. WHEN the REGISTRATION_ALLOWED_DOMAINS variable is empty or not set THEN the System SHALL allow registration from any email domain
3. WHEN the REGISTRATION_ALLOWED_DOMAINS variable contains whitespace around domain names THEN the System SHALL trim the whitespace and normalize the domains to lowercase
4. WHEN the REGISTRATION_ALLOWED_DOMAINS variable contains invalid domain formats THEN the System SHALL log a warning and skip the invalid entries
5. WHERE DISALLOW_REGISTRATION is true, THEN the System SHALL ignore the REGISTRATION_ALLOWED_DOMAINS setting and prevent all registration

Requirement 2

User Story: As a user attempting to register, I want clear feedback when my email domain is not allowed, so that I understand why my registration was rejected.

Acceptance Criteria

1. WHEN a user submits a registration form with an email domain not in the whitelist THEN the System SHALL reject the registration and return a 400 status code
2. WHEN a user submits a registration form with an email domain not in the whitelist THEN the System SHALL display the error message "Registration is restricted to specific email domains"
3. WHEN a user submits a registration form with an allowed email domain THEN the System SHALL proceed with the normal registration flow
4. WHEN a user submits a registration form with an email address containing uppercase characters THEN the System SHALL normalize it to lowercase before domain validation

Requirement 3

User Story: As an administrator, I want the domain restriction to apply consistently across all registration methods, so that the security policy is enforced uniformly.

Acceptance Criteria

1. WHEN domain restrictions are configured THEN the System SHALL apply validation to HTML form-based registration
2. WHEN domain restrictions are configured THEN the System SHALL apply validation to API-based registration
3. WHEN an administrator creates a user through the admin panel THEN the System SHALL bypass domain restrictions
4. WHEN domain restrictions are configured THEN the System SHALL apply validation before sending verification emails

Requirement 4

User Story: As a developer, I want the domain restriction logic to be testable and maintainable, so that I can verify correct behavior and easily modify the feature.

Acceptance Criteria

1. WHEN the domain validation function receives an email address and domain list THEN the System SHALL return a boolean indicating whether the email is allowed
2. WHEN the domain validation function receives a null or undefined email THEN the System SHALL return false
3. WHEN the domain validation function receives an empty domain list THEN the System SHALL return true for any valid email
4. WHEN the domain validation function receives an email with multiple @ symbols THEN the System SHALL extract the domain from the rightmost @ symbol