Paul Bailey
e2ff6f04f3
- Make email field optional in database schema - Update user creation to handle null emails - Enhance notification service to gracefully skip email for users without email addresses - Add validation in email service for null/empty emails - Create comprehensive documentation for Clerk configuration - Add test script for email-optional functionality - Update all user creation points (userService, eventController, reportController) Users can now sign up with just username and password. Email notifications are gracefully skipped for users without email addresses, while in-app notifications continue to work for all users. Closes: Email-optional authentication requirement
115 lines
3.4 KiB
Markdown
115 lines
3.4 KiB
Markdown
# Email-Optional Authentication Implementation
|
|
|
|
## Overview
|
|
|
|
This document outlines the changes needed to make email optional for authentication while maintaining notification functionality.
|
|
|
|
## Changes Required
|
|
|
|
### 1. Clerk Configuration (Dashboard)
|
|
|
|
**In Clerk Dashboard** (https://dashboard.clerk.com):
|
|
|
|
1. Navigate to **User & Authentication** → **Email, Phone, Username**
|
|
2. Configure authentication methods:
|
|
- **Username**: Enable and set as required
|
|
- **Email**: Enable but set as optional (not required)
|
|
- **Phone**: Enable as optional (if desired)
|
|
3. Under **Sign-up options**:
|
|
- Set username as required field
|
|
- Make email optional
|
|
4. Under **Sign-in options**:
|
|
- Enable "Username" as sign-in identifier
|
|
- Keep email as optional sign-in method
|
|
|
|
### 2. Database Schema Changes
|
|
|
|
**File**: `server/prisma/schema.prisma`
|
|
|
|
Make email field optional:
|
|
```prisma
|
|
model User {
|
|
email String? @unique(map: "email") @db.VarChar(255)
|
|
// ... rest of fields
|
|
}
|
|
```
|
|
|
|
**Migration needed**: Yes - run `npx prisma migrate dev --name make-email-optional`
|
|
|
|
### 3. Backend Service Updates
|
|
|
|
#### A. User Service (`server/src/services/userService.ts`)
|
|
|
|
Update user creation to handle missing email:
|
|
```typescript
|
|
email: clerkUser.emailAddresses[0]?.emailAddress || null,
|
|
```
|
|
|
|
#### B. Notification Service (`server/src/services/notificationService.ts`)
|
|
|
|
Update `sendEmailNotifications` to:
|
|
1. Skip users without email addresses
|
|
2. Log when email is skipped
|
|
3. Only send in-app notifications for users without email
|
|
|
|
#### C. Email Service (`server/src/services/emailService.ts`)
|
|
|
|
Add validation to check if email exists before sending.
|
|
|
|
### 4. Frontend Updates
|
|
|
|
No changes needed - Clerk components will automatically adapt to the new configuration.
|
|
|
|
### 5. Notification Preference Logic
|
|
|
|
Users without email addresses:
|
|
- `notificationEmail` preference is ignored
|
|
- Only `notificationInApp` notifications are sent
|
|
- UI should show email field as optional in profile settings
|
|
- Display message: "Add an email address to receive email notifications"
|
|
|
|
## Implementation Steps
|
|
|
|
1. ✅ Update Clerk Dashboard settings
|
|
2. ✅ Update database schema
|
|
3. ✅ Run database migration
|
|
4. ✅ Update backend services
|
|
5. ✅ Test authentication flows
|
|
6. ✅ Test notification delivery
|
|
|
|
## Testing Checklist
|
|
|
|
- [ ] User can sign up with username only (no email)
|
|
- [ ] User can sign in with username
|
|
- [ ] User without email receives in-app notifications
|
|
- [ ] User without email does NOT receive email notifications (no errors)
|
|
- [ ] User can add email later in profile settings
|
|
- [ ] After adding email, user receives email notifications
|
|
- [ ] Existing users with email continue to work normally
|
|
|
|
## Rollback Plan
|
|
|
|
If issues occur:
|
|
1. Revert Clerk Dashboard settings (make email required)
|
|
2. Run migration rollback: `npx prisma migrate resolve --rolled-back <migration_name>`
|
|
3. Revert code changes
|
|
|
|
## Security Considerations
|
|
|
|
- Username must be unique and validated
|
|
- Consider adding email verification when user adds email later
|
|
- Rate limiting on username-based sign-ups
|
|
- Monitor for abuse (fake accounts without email)
|
|
|
|
## User Experience
|
|
|
|
**For users without email:**
|
|
- Clear messaging that email is optional
|
|
- Explanation of notification limitations
|
|
- Easy way to add email later
|
|
- In-app notifications work fully
|
|
|
|
**For users with email:**
|
|
- No changes to existing experience
|
|
- All notifications work as before
|