[Backend] Implement Production-Grade Community Signup & Auth System with Security, Anti-Abuse, and Verification Flow

[abhishek-nexgen-dev]

Frontend Signup Page Issue

NexGenStudioDev/CommDesk#2

We are building a community-first authentication system:

Community registers
→ Owner account created
→ Email verification
→ Admin approval
→ Then login allowed

👉 Rule:

• Users cannot exist without a community

Reference:

---

🎯 Goals

Build a backend system that is:

• Secure (no hacks, no brute force)
• Scalable (handles many users)
• Abuse-resistant (prevents spam)
• Production-ready (real-world SaaS level)

---

🧱 Core Features

---

1. Community Signup

Endpoint

POST /api/v1/auth/signup-community

---

Flow

User submits form
→ Validate input
→ Check duplicates
→ Create community
→ Create owner account
→ Hash password
→ Generate email token
→ Send email (via queue)
→ Set status = pending
→ Save audit log

---

Validation

Use Zod:

• email format
• password strength
• valid URL
• required fields

---

Duplicate Protection

Check:

• community name
• official email
• domain

---

Slug Handling

Auto-generate slug:

apex-circle
apex-circle-1
apex-circle-2

---

Idempotency (IMPORTANT)

Prevent duplicate submissions:

• Use Idempotency-Key header

---

---

2. Email Verification

Endpoint

POST /api/v1/auth/verify-email

---

Flow

User clicks email link
→ Verify token
→ Check expiry
→ emailVerified = true
→ Log event

---

Edge Cases

• expired token
• invalid token
• already used

---

---

3. Admin Approval

Endpoint

PATCH /api/v1/admin/communities/:id/status

---

Status Flow

pending → under_review → approved → active

Other states:

• rejected
• suspended

---

Rule

❌ Login NOT allowed until approved

---

---

4. Login System

Endpoint

POST /api/v1/auth/login

---

Checks

• email exists
• password correct
• email verified
• community approved
• account not locked

---

On Success

• generate access token (short-lived)
• generate refresh token (rotating)

---

---

5. Refresh Token System (CRITICAL)

Storage

Store in DB/Redis:

RefreshToken {
  userId
  tokenHash
  expiresAt
  deviceInfo
  createdAt
}

---

Rules

• hash refresh token
• rotate on every use
• detect reuse attack → logout all sessions

---

---

6. Session & Device Management

Track:

• IP
• device
• user-agent

---

APIs

GET /sessions
DELETE /sessions/:id
DELETE /sessions (logout all)

---

---

7. Forgot Password / Reset Password

Endpoints

POST /auth/forgot-password
POST /auth/reset-password

---

Flow

User requests reset
→ token sent via email
→ user resets password
→ invalidate all sessions

---

---

🔐 Security (VERY IMPORTANT)

---

1. Password Security

• bcrypt (salt ≥ 10)
• never store plain password

---

2. Rate Limiting

Signup → 5/hour/IP
Login → 10/min/IP

Use Redis

---

3. Brute Force Protection

5 failed attempts → block 15 min
10 failed → account locked

Store:

failedLoginAttempts
lockUntil

---

4. CSRF Protection

If using cookies:

• CSRF token
• SameSite=strict

---

5. Token Security

• short-lived access token
• refresh token rotation
• revoke on logout

---

6. Abuse Detection (Advanced)

Detect:

• multiple signups from same IP
• disposable emails
• suspicious domains

---

7. Input Validation

Use Zod everywhere

---

---

🧾 Database Design

---

Community

name
slug
status
officialEmail
website
country
city
timezone
socialLinks
createdBy
createdAt
isDeleted

---

User

email
passwordHash
role = CommunityOwner
communityId
emailVerified
failedLoginAttempts
lockUntil
acceptedTermsAt

---

RefreshToken

userId
tokenHash
deviceInfo
expiresAt

---

Audit Logs

community_signup
user_created
email_verified
login_success
login_failed
account_locked
community_approved
password_reset

---

---

📧 Email System (Production)

Use queue system:

• BullMQ / RabbitMQ

---

Flow

Signup → push job → worker sends email

---

Required Emails

• signup confirmation
• email verification
• password reset
• approval/rejection

---

---

📦 File Upload (Logo)

• validate file type
• size limit
• store on S3 / Cloudinary

---

---

⚙️ Architecture (IMPORTANT)

Use clean structure:

controllers/
services/
repositories/
middlewares/
utils/
validators/

---

---

🧨 Error Handling

Global error handler:

try → throw → catch globally

Return:

success: false
message: "Something went wrong"

---

---

🔄 Transactions

Use DB transactions:

👉 If one step fails → rollback everything

---

---

📊 Observability

Track:

• signup rate
• login failures
• suspicious activity

---

Alerts

• high failed logins
• signup spikes
• email failures

---

---

🔐 RBAC (Future Ready)

Roles:

CommunityOwner
Admin
Moderator
Member

---

---

🌍 Environment Setup

DEV
STAGING
PROD

Use env variables for:

• JWT secrets
• DB URL
• email keys

---

---

🧪 Testing (MANDATORY)

---

Unit Tests

• validation
• hashing
• slug generation

---

Integration Tests

• full signup flow
• login flow
• email verification

---

Security Tests

• brute force attack
• rate limit
• token misuse

---

Coverage

Minimum 80%
Critical paths = 100%

---

---

🧠 Edge Cases

• duplicate submissions
• expired tokens
• invalid login
• DB failure
• email not sent
• retry logic

---

---

✅ Acceptance Criteria

✔ Community signup works
✔ Email verification works
✔ Admin approval works
✔ Login only after approval
✔ Refresh tokens secure
✔ Brute force protection active
✔ Rate limiting active
✔ Password reset works
✔ Sessions managed
✔ All edge cases handled
✔ Tests written
✔ No security issues