Skip to content

README.md

Latest commit

 

History

History
582 lines (466 loc) · 13.9 KB

README.md

File metadata and controls

582 lines (466 loc) · 13.9 KB
Raw

Restricted Registered Emails System

A comprehensive security solution for preventing registration with privileged, reserved, or system-critical email addresses. Includes backend API, PostgreSQL database, admin management UI, and integration examples for your registration endpoint.

🔒 Security Features

  • Three Matching Types: Exact match (localpart), domain-level blocking, and regex patterns
  • Multi-Domain Support: Apply global rules or domain-specific restrictions
  • Audit Trail: Complete logging of all blocklist changes with timestamps and user attribution
  • Flexible Management: Add/edit/delete entries, bulk import/export (CSV)
  • Pre-Populated Defaults: Includes common reserved addresses (admin, support, noreply, etc.)

📋 Table of Contents

🚀 Quick Start

Prerequisites

  • Node.js 18+
  • PostgreSQL 12+
  • npm or yarn

Backend Setup

cd backend
npm install
cp .env.example .env
# Edit .env with your database credentials
npm run db:migrate
npm run dev

Frontend Setup

cd frontend
npm install
npm run dev

Visit http://localhost:3001 to access the admin dashboard.

🏗️ Architecture

Backend Stack

  • Runtime: Node.js with Express.js
  • Language: TypeScript
  • Database: PostgreSQL with audit triggers
  • API: RESTful API with JSON responses

Frontend Stack

  • Framework: React 18 with TypeScript
  • Build Tool: Vite
  • Styling: Tailwind CSS
  • UI Components: Custom with Lucide icons

Database Schema

restricted_emails
├── id (UUID, PK)
├── pattern (VARCHAR, the email pattern)
├── type (VARCHAR: 'exact' | 'domain' | 'regex')
├── applicable_domains (TEXT[], NULL for all domains)
├── reason (TEXT, optional)
├── created_by (VARCHAR)
├── created_at (TIMESTAMP)
├── updated_at (TIMESTAMP)
├── is_active (BOOLEAN)
└── ...

restricted_emails_audit
├── id (UUID, PK)
├── restricted_email_id (UUID, FK)
├── action (VARCHAR: 'CREATE' | 'UPDATE' | 'DELETE')
├── pattern_before / pattern_after
├── type_before / type_after
├── domains_before / domains_after
├── reason_before / reason_after
├── changed_by (VARCHAR)
├── change_timestamp (TIMESTAMP)
└── ...

📦 Installation

1. Clone or Extract Files

cd /path/to/Restricted-Registered-Emails

2. Set Up Backend

cd backend
npm install
cp .env.example .env

Edit .env with your PostgreSQL credentials:

DATABASE_URL=postgresql://postgres:password@localhost:5432/restricted_emails_db
DB_HOST=localhost
DB_PORT=5432
DB_NAME=restricted_emails_db
DB_USER=postgres
DB_PASSWORD=yourpassword
PORT=3000
NODE_ENV=development
CORS_ORIGIN=http://localhost:3001

3. Initialize Database

npm run db:migrate

This will create all tables, indexes, triggers, and seed default restricted emails.

4. Start Backend Server

npm run dev

Server will start on http://localhost:3000

5. Set Up Frontend

cd ../frontend
npm install
npm run dev

Access the admin dashboard at http://localhost:3001

⚙️ Configuration

Environment Variables (Backend)

Variable Description Default
DATABASE_URL PostgreSQL connection string -
DB_HOST Database host localhost
DB_PORT Database port 5432
DB_NAME Database name restricted_emails_db
DB_USER Database user postgres
DB_PASSWORD Database password postgres
PORT Server port 3000
NODE_ENV Environment development
CORS_ORIGIN CORS allowed origin http://localhost:3001
JWT_SECRET (Optional) JWT secret for auth your-secret-key

Frontend Configuration

Edit frontend/vite.config.ts to change the API proxy target:

server: {
  proxy: {
    '/api': {
      target: 'http://localhost:3000',  // Change to your backend URL
      changeOrigin: true,
    },
  },
},

📚 API Documentation

Base URL

http://localhost:3000/api/blocklist

Endpoints

1. Get All Restricted Emails

GET /api/blocklist?page=1&pageSize=20&search=admin&type=exact&domain=example.com

Query Parameters:

  • page (integer, default: 1) - Page number
  • pageSize (integer, default: 20) - Entries per page
  • search (string) - Search by pattern
  • type (string) - Filter by type (exact, domain, regex)
  • domain (string) - Filter by applicable domain

Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "pattern": "admin",
      "type": "exact",
      "applicableDomains": null,
      "reason": "Reserved for admin accounts",
      "createdBy": "system",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "isActive": true
    }
  ],
  "total": 150,
  "page": 1,
  "pageSize": 20,
  "totalPages": 8
}

2. Get Single Entry

GET /api/blocklist/{id}

3. Create Restricted Email

POST /api/blocklist
Content-Type: application/json

{
  "pattern": "admin",
  "type": "exact",
  "applicableDomains": null,
  "reason": "Reserved for administrative accounts"
}

Response: 201 Created with created entry

4. Update Entry

PUT /api/blocklist/{id}
Content-Type: application/json

{
  "reason": "Updated reason"
}

5. Delete Entry

DELETE /api/blocklist/{id}

Response: 204 No Content (soft delete - marks as inactive)

6. Validate Email

POST /api/blocklist/validate
Content-Type: application/json

{
  "email": "admin@example.com",
  "domain": "example.com"
}

Response:

{
  "isBlocked": true,
  "blockedPattern": {
    "id": "...",
    "pattern": "admin",
    "type": "exact",
    "reason": "Reserved for admin accounts"
  },
  "reason": "This email address is reserved for system use."
}

7. Bulk Import

POST /api/blocklist/bulk-import
Content-Type: application/json

{
  "csvContent": "pattern,type,applicable_domains,reason\nadmin,exact,,Admin account\nsupport,exact,,Support team",
  "createdBy": "admin"
}

CSV Format:

pattern,type,applicable_domains,reason
admin,exact,,Reserved for admin accounts
support,exact,,Reserved for support team
noreply,exact,,Reserved for system notifications
security,exact,,Reserved for security team
help,exact,,Reserved for help desk

Response:

{
  "success": true,
  "inserted": 5,
  "errors": [],
  "data": [...]
}

8. Export Blocklist

GET /api/blocklist/export

Response: CSV file download

9. Get Audit Log (for entry)

GET /api/blocklist/{id}/audit?page=1&pageSize=20

10. Get Global Audit Log

GET /api/blocklist/audit/all?page=1&pageSize=20&action=CREATE

🖥️ Admin Dashboard

The React dashboard provides a user-friendly interface for managing the blocklist.

Features

  1. View Blocklist

    • Paginated table with sorting
    • Search by pattern
    • Filter by type (exact, domain, regex)
    • Filter by applicable domain

  2. Add Entry

    • Pattern input
    • Match type selector
    • Domain picker (multi-select or global)
    • Reason/notes field

  3. Edit Entry

    • Inline editing modal
    • Update any field
    • Automatic audit logging

  4. Delete Entry

    • Soft delete with confirmation
    • Preserves history in audit log

  5. Bulk Operations

    • CSV import with preview
    • Drag-and-drop file upload
    • CSV export with templates
    • Error reporting for failed imports

  6. Audit Log View

    • Track all changes
    • View who changed what and when
    • Filter by action type

🔗 Integration Guide

How to Integrate with Your Registration Endpoint

See backend/src/routes/register-example.ts for a complete example.

Step 1: Import the Service

import { EmailBlocklistService } from '../services/emailBlocklist';
import { getPool } from '../database/connection';

const blocklistService = new EmailBlocklistService(getPool());

Step 2: Check Email in Registration Handler

app.post('/api/register', async (req, res) => {
  const { email, password, domain } = req.body;

  // Validate email format
  if (!isValidEmailFormat(email)) {
    return res.status(400).json({ error: 'Invalid email format' });
  }

  // ✓ KEY STEP: Check if email is blocked
  const blockCheck = await blocklistService.isEmailBlocked(email, domain);
  if (blockCheck.isBlocked) {
    return res.status(403).json({
      error: blockCheck.reason || 'This email address cannot be used for registration',
      code: 'EMAIL_RESTRICTED',
    });
  }

  // Check if already registered
  const existing = await findUserByEmail(email);
  if (existing) {
    return res.status(409).json({ error: 'Email already registered' });
  }

  // Create user account
  const user = await createUser({ email, password });
  
  res.status(201).json({ userId: user.id });
});

Step 3: (Optional) Real-Time Validation Endpoint

app.post('/api/validate-email', async (req, res) => {
  const { email, domain } = req.body;

  const isBlocked = await blocklistService.isEmailBlocked(email, domain);
  const isRegistered = await checkUserExists(email);

  res.json({
    isValid: !isBlocked.isBlocked && !isRegistered,
    isBlocked: isBlocked.isBlocked,
    message: isBlocked.reason,
  });
});

Integration Points

  • Email Validation: Before creating user account in registration/signup endpoint
  • API Endpoints: Make requests to POST /api/blocklist/validate
  • Frontend: Show validation errors in signup form
  • Logging: Log blocked attempts for security monitoring

🧪 Testing

Run Unit Tests

cd backend
npm test

Run Specific Test File

npm test -- emailBlocklist.test.ts

Test Coverage

npm test -- --coverage

What's Tested

  • ✅ Exact match email validation
  • ✅ Domain-level blocking
  • ✅ Regex pattern matching
  • ✅ Case-insensitive matching
  • ✅ Whitespace trimming
  • ✅ Domain-specific restrictions
  • ✅ Invalid regex handling
  • ✅ Edge cases (multiple @, missing @, etc.)

🚢 Deployment

Production Checklist

  • Update .env with production database credentials
  • Set NODE_ENV=production
  • Enable HTTPS/SSL
  • Configure CORS for production domain
  • Set up database backups
  • Configure logging and monitoring
  • Rate limit registration endpoint
  • Set up audit log retention policy
  • Deploy backend and frontend separately
  • Test integration with your registration endpoint

Docker Deployment (Optional)

Create backend/Dockerfile:

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist ./dist
EXPOSE 3000
CMD ["node", "dist/index.js"]

Build and run:

docker build -t restricted-emails-api .
docker run -p 3000:3000 -e DATABASE_URL=... restricted-emails-api

Environment-Specific Configs

Development:

NODE_ENV=development
CORS_ORIGIN=http://localhost:3001

Production:

NODE_ENV=production
CORS_ORIGIN=https://yourdomain.com
DATABASE_URL=postgresql://prod_user:secure_password@prod-db-host:5432/restricted_emails_db

📊 Matching Types Explained

1. Exact Match

Matches the local part of the email exactly (case-insensitive).

Examples:

  • Pattern: admin → Blocks: admin@any.com, ADMIN@example.com
  • Pattern: support → Blocks: support@example.com, support@other.io

2. Domain Match

Matches specific domain(s).

Examples:

  • Pattern: example.com → Blocks: anyone@example.com, user@sub.example.com
  • Pattern: @domain.com → Blocks: any@domain.com

3. Regex Pattern

Uses regular expressions for complex matching rules.

Examples:

  • Pattern: ^noreply-.*@example\.com$ → Blocks: noreply-system@example.com, noreply-alerts@example.com
  • Pattern: admin.*@(example|test)\.com → Blocks: admin.main@example.com, adminuser@test.com, etc.

🔍 Common Use Cases

1. Block All Noreply Variations Across All Domains

Pattern: noreply | Type: Exact | Domains: None (global)

2. Block Specific Domain

Pattern: suspicious-domain.com | Type: Domain | Domains: None

3. Block Admin Accounts Only for One Domain

Pattern: admin | Type: Exact | Domains: example.com

4. Block Regex Patterns for Multiple Domains

Pattern: ^(noreply|mailer|daemon)-.* | Type: Regex | Domains: domain1.com, domain2.com

📝 Default Blocklist

Out-of-the-box, these addresses are blocked globally:

  • admin, administrator - Administrative accounts
  • support, help - Support teams
  • noreply, no-reply - Notification systems
  • security, abuse - Security/abuse reporting
  • contact, info - Generic addresses
  • sales - Sales team
  • root, postmaster, mailer-daemon - System accounts

Edit or delete these from the admin dashboard as needed.

🆘 Troubleshooting

Database Connection Error

Error: connect ECONNREFUSED 127.0.0.1:5432

Solution: Ensure PostgreSQL is running. Check DB_HOST, DB_PORT, DB_USER, DB_PASSWORD in .env.

API Returns 403 for All Registrations

Solution: Check the audit log to see which pattern is blocking. The blocklist may be too strict. Adjust domain restrictions if needed.

Regex Pattern Not Matching

Solution: Test your regex in a tool like regex101.com. Remember patterns are case-insensitive by default.

CORS Errors in Frontend

Solution: Update CORS_ORIGIN in .env to match your frontend URL.

📄 License

MIT

Support

For issues, questions, or feature requests, please refer to the integration documentation or contact your security team.