sojorn/sojorn_docs/ENHANCED_REGISTRATION_FLOW.md

Enhanced Registration Flow - Implementation Guide

🎯 Overview

Complete registration system with Cloudflare Turnstile verification, terms acceptance, and email preferences. Provides robust security and compliance while maintaining user experience.

🔐 Security Features

Cloudflare Turnstile Integration

• Bot Protection: Prevents automated registrations
• Human Verification: Ensures real users only
• Development Bypass: Automatic success when no secret key configured
• IP Validation: Optional remote IP verification
• Error Handling: User-friendly error messages

Required Validations

• ✅ Turnstile Token: Must be valid and verified
• ✅ Terms Acceptance: Must accept Terms of Service
• ✅ Privacy Acceptance: Must accept Privacy Policy
• ✅ Email Format: Valid email address required
• ✅ Password Strength: Minimum 6 characters
• ✅ Handle Uniqueness: No duplicate handles allowed
• ✅ Email Uniqueness: No duplicate emails allowed

📧 Email Preferences

Newsletter Opt-In

• Optional: User can choose to receive newsletter emails
• Default: false (user must explicitly opt-in)
• Purpose: Marketing updates, feature announcements

Contact Opt-In

• Optional: User can choose to receive contact emails
• Default: false (user must explicitly opt-in)
• Purpose: Transactional emails, important updates

🔧 API Specification

Registration Endpoint

POST /api/v1/auth/register
Content-Type: application/json

Request Body

{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "handle": "username",
  "display_name": "User Display Name",
  "turnstile_token": "0xAAAAAA...",
  "accept_terms": true,
  "accept_privacy": true,
  "email_newsletter": false,
  "email_contact": true
}

Required Fields

• email (string, valid email)
• password (string, min 6 chars)
• handle (string, min 3 chars)
• display_name (string)
• turnstile_token (string)
• accept_terms (boolean, must be true)
• accept_privacy (boolean, must be true)

Optional Fields

• email_newsletter (boolean, default false)
• email_contact (boolean, default false)

Success Response

{
  "email": "user@example.com",
  "message": "Registration successful. Please verify your email to activate your account.",
  "state": "verification_pending"
}

Error Responses

// Missing Turnstile token
{"error": "Key: 'RegisterRequest.TurnstileToken' Error:Field validation for 'TurnstileToken' failed on the 'required' tag"}

// Terms not accepted
{"error": "Key: 'RegisterRequest.AcceptTerms' Error:Field validation for 'AcceptTerms' failed on the 'required' tag"}

// Turnstile verification failed
{"error": "Security check failed, please try again"}

// Email already exists
{"error": "Email already registered"}

// Handle already taken
{"error": "Handle already taken"}

🗄️ Database Schema

Users Table Updates

-- New columns added
ALTER TABLE users ADD COLUMN IF NOT EXISTS email_newsletter BOOLEAN DEFAULT false;
ALTER TABLE users ADD COLUMN IF NOT EXISTS email_contact BOOLEAN DEFAULT false;

-- Performance indexes
CREATE INDEX IF NOT EXISTS idx_users_email_newsletter ON users(email_newsletter);
CREATE INDEX IF NOT EXISTS idx_users_email_contact ON users(email_contact);

User Record Example

SELECT email, status, email_newsletter, email_contact, created_at 
FROM users 
WHERE email = 'user@example.com';

-- Result:
-- email                | status  | email_newsletter | email_contact | created_at
-- user@example.com     | pending | false           | true          | 2026-02-05 15:59:48

⚙️ Configuration

Environment Variables

# Cloudflare Turnstile
TURNSTILE_SECRET_KEY=your_turnstile_secret_key_here

# Development Mode (no verification)
TURNSTILE_SECRET_KEY=""

Frontend Integration

Turnstile Widget

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

<form id="registration-form">
  <!-- Your form fields -->
  <div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY"></div>
  <button type="submit">Register</button>
</form>

JavaScript Integration

const form = document.getElementById('registration-form');
form.addEventListener('submit', async (e) => {
  e.preventDefault();
  
  const turnstileToken = turnstile.getResponse();
  if (!turnstileToken) {
    alert('Please complete the security check');
    return;
  }
  
  const formData = {
    email: document.getElementById('email').value,
    password: document.getElementById('password').value,
    handle: document.getElementById('handle').value,
    display_name: document.getElementById('displayName').value,
    turnstile_token: turnstileToken,
    accept_terms: document.getElementById('terms').checked,
    accept_privacy: document.getElementById('privacy').checked,
    email_newsletter: document.getElementById('newsletter').checked,
    email_contact: document.getElementById('contact').checked
  };
  
  try {
    const response = await fetch('/api/v1/auth/register', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(formData)
    });
    
    const result = await response.json();
    if (response.ok) {
      // Handle success
      console.log('Registration successful:', result);
    } else {
      // Handle error
      console.error('Registration failed:', result.error);
    }
  } catch (error) {
    console.error('Network error:', error);
  }
});

🔄 Registration Flow

Step-by-Step Process

1. 📝 User fills registration form

   • Email, password, handle, display name
   • Accepts terms and privacy policy
   • Chooses email preferences
   • Completes Turnstile challenge

2. 🔐 Frontend validation

   • Required fields checked
   • Email format validated
   • Terms acceptance verified

3. 🛡️ Security verification

   • Turnstile token sent to backend
   • Cloudflare validation performed
   • Bot protection enforced

4. ✅ Backend validation

   • Email uniqueness checked
   • Handle uniqueness checked
   • Password strength verified

5. 👤 User creation

   • Password hashed with bcrypt
   • User record created with preferences
   • Profile record created
   • Verification token generated

6. 📧 Email verification

   • Verification email sent
   • User status set to "pending"
   • 24-hour token expiry

7. 🎉 Success response

   • Confirmation message returned
   • Next steps communicated

🧪 Testing

Development Mode

# No Turnstile verification when secret key is empty
TURNSTILE_SECRET_KEY=""

Test Cases

# Valid registration
curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"TestPassword123!","handle":"test","display_name":"Test","turnstile_token":"test_token","accept_terms":true,"accept_privacy":true,"email_newsletter":true,"email_contact":false}'

# Missing Turnstile token (should fail)
curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"TestPassword123!","handle":"test","display_name":"Test","accept_terms":true,"accept_privacy":true}'

# Terms not accepted (should fail)
curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"TestPassword123!","handle":"test","display_name":"Test","turnstile_token":"test_token","accept_terms":false,"accept_privacy":true}'

🚀 Deployment Status

✅ Fully Implemented

• Cloudflare Turnstile integration
• Terms and privacy acceptance
• Email preference tracking
• Database schema updates
• Comprehensive validation
• Error handling and logging

✅ Production Ready

• Security verification active
• User preferences stored
• Validation rules enforced
• Error messages user-friendly
• Development bypass available

🔧 Configuration Required

• Add Turnstile secret key to environment
• Configure Turnstile site key in frontend
• Update terms and privacy policy links
• Test with real Turnstile implementation

The enhanced registration flow provides robust security, legal compliance, and user control over email communications while maintaining excellent user experience! 🎉