Developer Documentation

cd bulk-mailer
npm install
npm run dev

Create a .env.local file with the following variables:

JWT_SECRET=your-secret-here
ENCRYPTION_KEY=your-encryption-key-here
CSRF_SECRET=your-csrf-secret-here
SMTP_SERVER=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USERNAME=apikey
SMTP_PASSWORD=your-sendgrid-api-key
FROM_EMAIL=noreply@yourdomain.com

npm run dev

The application will start on http://localhost:3000

• JWT-based authentication (stateless)
• CSRF protection with token validation
• Security headers via middleware
• Password hashing with bcryptjs
• Encryption for sensitive data (AES-256-GCM)
• Rate limiting (in-memory)

• In-memory database with singleton pattern
• Email queue processing
• Campaign management
• Contact management
• SMTP provider configuration
• Template variable substitution

• Durable Objects for persistent storage
• Cloudflare KV Store for distributed caching
• R2 buckets for file storage
• Bounce handling
• Delivery tracking
• Multi-tenant support

1. User registers with email and password
2. Password is hashed with bcryptjs (10 rounds)
3. JWT token is generated with 24-hour expiry
4. CSRF token is generated for state-changing operations
5. Tokens are stored in localStorage on client
6. All requests send JWT in Authorization header

interface JWTPayload {
  userId: string
  email: string
  role: string
  iat: number
  exp: number
}

All state-changing operations (POST, PUT, DELETE, PATCH) require CSRF token validation:

• CSRF tokens are JWT-based (stateless)
• Generated upon login/register
• Stored in localStorage as csrf_token
• Sent in X-CSRF-Token header
• Verified on backend before processing
• No session storage required

Current implementation uses in-memory storage with singleton pattern for development and testing.

Persistent storage will use Cloudflare Durable Objects with the following structure:

• UsersDurableObject: User data and authentication
• SMTPProvidersDurableObject: SMTP configurations
• ContactsDurableObject: Contact information
• CampaignsDurableObject: Campaign definitions
• EmailQueueDurableObject: Email sending queue

Sensitive data (SMTP passwords) is encrypted using AES-256-GCM before storage:

import { encryptData, decryptData } from '@/lib/encryption'

const encrypted = await encryptData(smtpPassword)
const decrypted = await decryptData(encrypted)

All endpoints validate input using Zod schemas:

import { z } from 'zod'

const contactSchema = z.object({
  email: z.string().email('Invalid email'),
  firstName: z.string().optional(),
  tags: z.array(z.string()).default([])
})

const data = contactSchema.parse(body)

• Phase 2: In-memory rate limiting per IP
• Phase 3: Distributed rate limiting with KV Store
• Configurable per endpoint
• Returns 429 Too Many Requests when exceeded

• Hashed with bcryptjs (10 rounds)
• Never stored in plain text
• Never transmitted in URLs
• Always sent over HTTPS only

npm test                  # Run all tests
npm run test:watch      # Watch mode
npm run test:coverage   # Coverage report

Test suites: Auth (8 tests), CSRF (7 tests), Utils (7 tests), Encryption (2 tests)

Test API endpoints with request validation and response verification:

import request from 'supertest'
import { POST } from '@/app/api/contacts/route'

describe('Contacts API', () => {
  it('should create contact with CSRF token', async () => {
    const res = await request(app)
      .post('/api/contacts')
      .set('Authorization', `Bearer ${token}`)
      .set('X-CSRF-Token', csrfToken)
      .send({ email: 'test@example.com' })
    
    expect(res.status).toBe(200)
  })
})

1. Setup SMTP credentials (Gmail, SendGrid, or Mailgun)
2. Create test user and SMTP provider
3. Create test contacts
4. Create test campaign with template
5. Trigger email send
6. Verify email received with variables replaced

• Cloudflare account
• wrangler CLI installed
• Environment variables configured
• All tests passing

1. Build project: npm run build
2. Run tests: npm test
3. Set environment variables in Cloudflare Pages
4. Deploy: npm run deploy
5. Verify endpoints accessible
6. Monitor logs for errors

Configure these in Cloudflare Pages dashboard, never commit to git:

• JWT_SECRET: Long random string
• ENCRYPTION_KEY: 32+ character string
• CSRF_SECRET: Long random string
• SMTP_SERVER: Your mail server
• SMTP_PORT: Usually 587 or 465
• SMTP_USERNAME: Authentication username
• SMTP_PASSWORD: Authentication password
• FROM_EMAIL: Sender email address

Need help? Reach out through these channels:

• Email: hello@nsisonglabs.com
• Twitter: @1cbyc
• GitHub Issues: github.com/1cbyc/mailer/issues