@xenterprises/fastify-xtwilio 1.0.0

package/SECURITY.md

@@ -0,0 +1,721 @@
+# Security Guidelines for xTwilio
+
+This document outlines security best practices for using the xTwilio plugin to protect your communications infrastructure, API credentials, and customer data.
+
+## Table of Contents
+
+1. [Credential Management](#credential-management)
+2. [API Key Security](#api-key-security)
+3. [Webhook Security](#webhook-security)
+4. [Input Validation](#input-validation)
+5. [Phone Number Handling](#phone-number-handling)
+6. [Email Security](#email-security)
+7. [Error Handling](#error-handling)
+8. [Rate Limiting](#rate-limiting)
+9. [Compliance & Privacy](#compliance--privacy)
+10. [Incident Response](#incident-response)
+
+---
+
+## 1. Credential Management
+
+### Never Hardcode Credentials
+
+Always use environment variables for sensitive credentials. Never commit API keys, auth tokens, or secrets to version control.
+
+**❌ WRONG:**
+
+```javascript
+const fastify = await fastify.register(xTwilio, {
+  twilio: {
+    accountSid: 'AC1234567890abcdef1234567890abcdef',
+    authToken: 'your_secret_auth_token_here',
+  }
+});
+```
+
+**✅ CORRECT:**
+
+```javascript
+const fastify = await fastify.register(xTwilio, {
+  twilio: {
+    accountSid: process.env.TWILIO_ACCOUNT_SID,
+    authToken: process.env.TWILIO_AUTH_TOKEN,
+  }
+});
+```
+
+### Environment Variable Management
+
+1. Create a `.env` file locally (never commit to Git)
+2. Use `.env.example` as a template for developers
+3. In production, set environment variables through your hosting platform:
+   - **Vercel**: Project Settings → Environment Variables
+   - **AWS**: Systems Manager → Parameter Store or Secrets Manager
+   - **Docker**: Use Docker secrets or `.env` files in secure storage
+   - **Heroku**: Config Vars in app settings
+
+### Rotating Credentials
+
+Regularly rotate API keys and auth tokens:
+
+1. Generate new credentials in Twilio/SendGrid dashboards
+2. Update environment variables in production
+3. Test with new credentials before removing old ones
+4. Revoke old credentials once new ones are verified
+
+---
+
+## 2. API Key Security
+
+### Twilio Credentials
+
+Your Twilio Account SID and Auth Token provide full access to your Twilio account. Treat them like passwords.
+
+**Protection Level: CRITICAL**
+
+```bash
+# Store in a secure vault, not in code or config files
+TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx      # 34 chars
+TWILIO_AUTH_TOKEN=your_secret_token_here               # Very long string
+```
+
+### SendGrid API Key
+
+SendGrid API keys have full API access to your account.
+
+**Protection Level: CRITICAL**
+
+```bash
+# Always use the least-privileged API key
+# Create keys in SendGrid dashboard with specific permissions
+SENDGRID_API_KEY=SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+#### SendGrid Key Permissions
+
+When creating API keys, enable only the permissions you need:
+
+- **For sending only**: Enable `mail.send` only
+- **For contact management**: Enable `contacts.read`, `contacts.write`
+- **For list management**: Enable `lists.read`, `lists.write`
+- **For templates**: Enable `templates.read`
+
+Example: Key for sending emails only
+
+```
+Mail Send: Full Access
+Contacts: None
+Lists: None
+```
+
+### Logging & Exposure
+
+Never log credentials in any form:
+
+```javascript
+// ❌ WRONG - Exposes API key in logs
+console.log('Config:', {
+  twilioAccountSid: process.env.TWILIO_ACCOUNT_SID,
+  twilioAuthToken: process.env.TWILIO_AUTH_TOKEN,  // Exposed!
+  sendgridApiKey: process.env.SENDGRID_API_KEY,     // Exposed!
+});
+
+// ✅ CORRECT - Safe logging with masking
+console.log('Config loaded:', {
+  twilio: 'configured',
+  sendgrid: 'configured',
+});
+```
+
+---
+
+## 3. Webhook Security
+
+### Webhook Signature Validation
+
+Always validate Twilio webhooks to ensure they come from Twilio:
+
+```javascript
+import twilio from 'twilio';
+
+// Verify webhook signature
+const isValidRequest = twilio.validateRequest(
+  process.env.TWILIO_AUTH_TOKEN,
+  req.headers['x-twilio-signature'],
+  'https://yourdomain.com/webhooks/twilio',
+  req.rawBody
+);
+
+if (!isValidRequest) {
+  return reply.code(403).send({ error: 'Invalid signature' });
+}
+```
+
+### Webhook Configuration
+
+1. Use HTTPS endpoints only (never HTTP in production)
+2. Set strong webhook secrets:
+   ```bash
+   TWILIO_CONVERSATIONS_WEBHOOK_SECRET=your_strong_random_secret
+   ```
+3. Validate signatures in all webhook handlers
+4. Implement request logging (without exposing sensitive data)
+
+### Webhook URL Security
+
+- Use unique paths: `/webhooks/twilio` not just `/webhook`
+- Implement IP allowlisting if possible (restrict to Twilio IPs)
+- Require authentication tokens in webhook headers
+- Implement rate limiting on webhook endpoints
+
+**Example Secure Webhook Handler:**
+
+```javascript
+import crypto from 'crypto';
+
+fastify.post('/webhooks/twilio', async (request, reply) => {
+  // 1. Validate signature
+  const signature = request.headers['x-twilio-signature'];
+  const expectedSignature = crypto
+    .createHmac('sha1', process.env.TWILIO_AUTH_TOKEN)
+    .update(`https://yourdomain.com/webhooks/twilio${JSON.stringify(request.body)}`)
+    .digest('base64');
+
+  if (signature !== expectedSignature) {
+    fastify.log.error('Invalid webhook signature');
+    return reply.code(403).send({ error: 'Unauthorized' });
+  }
+
+  // 2. Process webhook
+  const { MessageSid, From, Body } = request.body;
+
+  // 3. Don't expose sensitive data in response
+  return reply.code(200).send({ status: 'received' });
+});
+```
+
+---
+
+## 4. Input Validation
+
+### Phone Number Validation
+
+Always validate phone numbers before sending SMS:
+
+```javascript
+// ✅ CORRECT - Validate phone number
+const validation = await fastify.sms.validatePhoneNumber(phoneNumber, {
+  countryCode: 'US'
+});
+
+if (!validation.isValid) {
+  return reply.code(400).send({
+    error: 'Invalid phone number',
+    details: validation.error
+  });
+}
+
+await fastify.sms.send(validation.phoneNumber, message);
+```
+
+### Message Content Validation
+
+Validate message content to prevent injection attacks:
+
+```javascript
+// ❌ WRONG - Accepts arbitrary input
+await fastify.sms.send(phoneNumber, userInput);
+
+// ✅ CORRECT - Validates message content
+function validateMessage(message) {
+  if (!message || typeof message !== 'string') {
+    throw new Error('Message must be a non-empty string');
+  }
+  if (message.length > 160) {
+    throw new Error('Message exceeds SMS length limit');
+  }
+  // Remove potentially harmful characters
+  return message.replace(/[<>\"']/g, '');
+}
+
+const validMessage = validateMessage(userInput);
+await fastify.sms.send(phoneNumber, validMessage);
+```
+
+### Email Input Validation
+
+Validate email addresses before sending:
+
+```javascript
+// Use a robust email validation library
+import { validateEmail } from 'email-validator';
+
+const isValid = validateEmail(userEmail);
+if (!isValid) {
+  return reply.code(400).send({ error: 'Invalid email address' });
+}
+
+// Or validate through SendGrid
+const validation = await fastify.email.validate(userEmail);
+if (!validation.isValid) {
+  return reply.code(400).send({ error: 'Email address not deliverable' });
+}
+
+await fastify.email.send(userEmail, subject, html);
+```
+
+---
+
+## 5. Phone Number Handling
+
+### Prevent SMS Bombing
+
+Implement rate limiting to prevent SMS abuse:
+
+```javascript
+import rateLimit from '@fastify/rate-limit';
+
+// Add rate limiting plugin
+await fastify.register(rateLimit, {
+  max: 10,  // Maximum 10 requests
+  timeWindow: '15 minutes'
+});
+
+fastify.post('/send-sms', async (request, reply) => {
+  const { phoneNumber, message } = request.body;
+
+  // Check rate limit (automatic with plugin)
+
+  await fastify.sms.send(phoneNumber, message);
+  return { status: 'sent' };
+});
+```
+
+### Phone Number Privacy
+
+Don't expose full phone numbers in logs or responses:
+
+```javascript
+// ❌ WRONG - Exposes full phone number
+fastify.log.info('SMS sent to:', phoneNumber);
+
+// ✅ CORRECT - Masks phone number
+function maskPhoneNumber(phone) {
+  const last4 = phone.slice(-4);
+  const masked = '*'.repeat(phone.length - 4) + last4;
+  return masked;
+}
+
+fastify.log.info('SMS sent to:', maskPhoneNumber(phoneNumber));
+```
+
+### International Phone Numbers
+
+Handle international numbers securely:
+
+```javascript
+// Use Twilio's Lookup API to validate international numbers
+const validation = await fastify.sms.validatePhoneNumber(
+  phoneNumber,
+  {
+    type: 'carrier',
+    countryCode: 'FR'  // Specify country for context
+  }
+);
+
+// Check for expensive operations (video calls, international rates)
+if (validation.carrier && validation.carrierType === 'voip') {
+  // Handle VOIP numbers differently if needed
+}
+```
+
+---
+
+## 6. Email Security
+
+### Prevent Email Header Injection
+
+Sanitize email headers to prevent injection attacks:
+
+```javascript
+// ❌ WRONG - Unsafe headers
+await fastify.email.send(
+  userEmail,
+  userSubject,  // User input in header!
+  html
+);
+
+// ✅ CORRECT - Sanitized headers
+function sanitizeHeader(header) {
+  // Remove newlines, carriage returns, and other injection vectors
+  return header.replace(/[\r\n]/g, '');
+}
+
+const safeSubject = sanitizeHeader(userSubject);
+await fastify.email.send(userEmail, safeSubject, html);
+```
+
+### Attachment Security
+
+Be careful with email attachments:
+
+```javascript
+// ❌ WRONG - Accepts any file
+await fastify.email.sendWithAttachments(
+  userEmail,
+  subject,
+  html,
+  userProvidedAttachments  // Dangerous!
+);
+
+// ✅ CORRECT - Validates attachments
+function validateAttachment(attachment) {
+  const MAX_SIZE = 25 * 1024 * 1024; // 25 MB
+  const ALLOWED_TYPES = [
+    'application/pdf',
+    'image/jpeg',
+    'image/png',
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+  ];
+
+  if (Buffer.byteLength(attachment.content, 'base64') > MAX_SIZE) {
+    throw new Error('Attachment too large');
+  }
+
+  if (!ALLOWED_TYPES.includes(attachment.type)) {
+    throw new Error('File type not allowed');
+  }
+
+  return attachment;
+}
+
+const validAttachments = userAttachments.map(validateAttachment);
+await fastify.email.sendWithAttachments(userEmail, subject, html, validAttachments);
+```
+
+### Unsubscribe Links
+
+Always include unsubscribe functionality in marketing emails:
+
+```javascript
+const htmlWithUnsubscribe = `
+  ${htmlContent}
+  <p>
+    <a href="https://yourdomain.com/unsubscribe?id=${userId}">Unsubscribe</a>
+  </p>
+`;
+
+await fastify.email.send(userEmail, subject, htmlWithUnsubscribe);
+```
+
+### SPF, DKIM, and DMARC Configuration
+
+Set up email authentication in your SendGrid account:
+
+1. **SPF (Sender Policy Framework)**
+   - Add SPF record to DNS: `v=spf1 sendgrid.net ~all`
+
+2. **DKIM (DomainKeys Identified Mail)**
+   - Enable DKIM in SendGrid dashboard
+   - Add DKIM records to DNS
+
+3. **DMARC (Domain-based Message Authentication)**
+   - Set DMARC policy: `v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com`
+
+---
+
+## 7. Error Handling
+
+### Don't Expose Sensitive Data in Errors
+
+Never include credentials, tokens, or full API responses in error messages:
+
+```javascript
+// ❌ WRONG - Exposes sensitive information
+fastify.post('/send-sms', async (request, reply) => {
+  try {
+    await fastify.sms.send(phoneNumber, message);
+  } catch (error) {
+    fastify.log.error('Full error:', error);  // Logs sensitive details!
+    return reply.code(500).send(error);        // Sends raw error to client!
+  }
+});
+
+// ✅ CORRECT - Safe error handling
+fastify.post('/send-sms', async (request, reply) => {
+  try {
+    await fastify.sms.send(phoneNumber, message);
+  } catch (error) {
+    // Log full error internally for debugging
+    fastify.log.error('SMS send failed', {
+      code: error.code,
+      status: error.status,
+      // Don't log: message, accountSid, authToken
+    });
+
+    // Return safe error to client
+    if (error.status === 400) {
+      return reply.code(400).send({
+        error: 'Invalid phone number or message'
+      });
+    }
+
+    return reply.code(500).send({
+      error: 'Failed to send message. Please try again later.'
+    });
+  }
+});
+```
+
+### Structured Error Logging
+
+Use structured logging to capture errors without exposing secrets:
+
+```javascript
+function logError(context, error) {
+  fastify.log.error({
+    timestamp: new Date().toISOString(),
+    context,
+    errorCode: error.code,
+    errorStatus: error.status,
+    message: 'Safe error description here',
+    // Never include:
+    // - authToken
+    // - apiKey
+    // - phoneNumber (full)
+    // - email addresses
+    // - rawErrorMessage
+  });
+}
+```
+
+---
+
+## 8. Rate Limiting
+
+### SMS Rate Limiting
+
+Prevent SMS spam with rate limiting:
+
+```javascript
+// Configure in .env
+SMS_RATE_LIMIT_PER_MINUTE=10
+
+// Implement in your code
+async function sendSMS(phoneNumber, message) {
+  // Check rate limit for this phone number
+  const key = `sms:${phoneNumber}`;
+  const count = await fastify.redis.incr(key);
+
+  if (count === 1) {
+    // Reset counter every minute
+    await fastify.redis.expire(key, 60);
+  }
+
+  if (count > parseInt(process.env.SMS_RATE_LIMIT_PER_MINUTE || '10')) {
+    throw new Error('Rate limit exceeded for this phone number');
+  }
+
+  return await fastify.sms.send(phoneNumber, message);
+}
+```
+
+### Email Rate Limiting
+
+Prevent email abuse:
+
+```javascript
+// Configure in .env
+EMAIL_RATE_LIMIT_PER_MINUTE=5
+
+// Implement in your code
+async function sendEmail(recipientEmail, subject, html) {
+  const key = `email:${recipientEmail}`;
+  const count = await fastify.redis.incr(key);
+
+  if (count === 1) {
+    await fastify.redis.expire(key, 60);
+  }
+
+  if (count > parseInt(process.env.EMAIL_RATE_LIMIT_PER_MINUTE || '5')) {
+    throw new Error('Rate limit exceeded for this recipient');
+  }
+
+  return await fastify.email.send(recipientEmail, subject, html);
+}
+```
+
+---
+
+## 9. Compliance & Privacy
+
+### GDPR Compliance
+
+- **Right to Access**: Maintain records of messages sent to users
+- **Right to Erasure**: Delete user data upon request
+- **Right to Rectification**: Allow users to update contact information
+- **Consent**: Maintain proof of user consent before sending marketing emails
+
+```javascript
+// Example: Request to delete user data
+fastify.delete('/api/users/:userId/data', async (request, reply) => {
+  const { userId } = request.params;
+
+  // Delete from your database
+  await db.users.delete(userId);
+
+  // Request deletion from Twilio (contact Twilio support)
+  // Request deletion from SendGrid contacts
+  await fastify.email.deleteContact(userId);
+
+  return { status: 'deleted' };
+});
+```
+
+### SMS Compliance (TCPA)
+
+**In the United States**, SMS messages are regulated by TCPA:
+
+- **Consent**: Obtain explicit written consent before sending SMS
+- **Opt-out**: Honor opt-out requests immediately
+- **Headers**: Include sender identification
+- **Timing**: Don't send SMS between 9 PM and 8 AM recipient's time zone
+
+```javascript
+// Check consent before sending
+async function sendCompliantSMS(phoneNumber, message) {
+  const user = await db.users.findByPhone(phoneNumber);
+
+  if (!user.smsConsent) {
+    throw new Error('User has not consented to SMS');
+  }
+
+  if (user.unsubscribedFromSMS) {
+    throw new Error('User has opted out of SMS');
+  }
+
+  return await fastify.sms.send(phoneNumber, message);
+}
+```
+
+### Email Compliance (CAN-SPAM)
+
+**In the United States**, email marketing is regulated by CAN-SPAM:
+
+- **Subject**: Must not be deceptive
+- **Identification**: Identify message as advertisement
+- **Reply Address**: Provide valid reply-to address
+- **Unsubscribe**: Honor unsubscribe requests within 10 business days
+
+```javascript
+// Send CAN-SPAM compliant email
+async function sendMarketingEmail(to, subject, html) {
+  const complianceFooter = `
+    <footer style="margin-top: 2rem; padding: 1rem; border-top: 1px solid #ddd; font-size: 0.8rem;">
+      <p>Your Company Name<br/>
+      123 Business St<br/>
+      City, ST 12345</p>
+      <p><a href="https://yourdomain.com/unsubscribe?email=${encodeURIComponent(to)}">
+        Unsubscribe from this mailing list
+      </a></p>
+    </footer>
+  `;
+
+  return await fastify.email.send(
+    to,
+    `[ADVERTISEMENT] ${subject}`,
+    `${html}${complianceFooter}`,
+    { replyTo: 'support@yourdomain.com' }
+  );
+}
+```
+
+---
+
+## 10. Incident Response
+
+### What To Do If Credentials Are Exposed
+
+1. **Immediately Revoke Credentials**
+   - Twilio: https://console.twilio.com/ → Account → Security → Auth Tokens
+   - SendGrid: https://app.sendgrid.com/settings/api_keys
+   - Delete the exposed credentials
+
+2. **Generate New Credentials**
+   - Create new Auth Token/API Key in the respective dashboard
+   - Update all environment variables
+
+3. **Audit Recent Activity**
+   - Check Twilio audit logs for unauthorized API calls
+   - Check SendGrid logs for unauthorized email sends
+   - Review SMS/call logs for suspicious activity
+
+4. **Notify Users (If Applicable)**
+   - If user data was accessed, notify affected users
+   - Document the breach for regulatory reporting
+
+5. **Update Infrastructure**
+   - Restart all applications with new credentials
+   - Verify no hardcoded credentials in code repositories
+   - Scan codebase for exposed secrets
+
+### Monitoring for Suspicious Activity
+
+```javascript
+// Monitor for unusual SMS volume
+fastify.addHook('onResponse', async (request, reply) => {
+  if (request.url.includes('/send-sms')) {
+    const metric = {
+      timestamp: Date.now(),
+      status: reply.statusCode,
+      endpoint: request.url,
+      ip: request.ip
+    };
+
+    await fastify.redis.lpush('sms:metrics', JSON.stringify(metric));
+
+    // Alert on 50+ SMS in 1 minute
+    const count = await fastify.redis.lrange('sms:metrics', 0, -1);
+    const recentCount = count.filter(m => {
+      const data = JSON.parse(m);
+      return Date.now() - data.timestamp < 60000;
+    }).length;
+
+    if (recentCount > 50) {
+      fastify.log.error('ALERT: High SMS volume detected', { count: recentCount });
+      // Send alert to security team
+    }
+  }
+});
+```
+
+### Security Checklist
+
+- [ ] All credentials stored in environment variables (not in code)
+- [ ] `.env` file added to `.gitignore`
+- [ ] Webhook signatures validated
+- [ ] HTTPS enforced for all endpoints
+- [ ] Input validation implemented
+- [ ] Error handling sanitized (no credential exposure)
+- [ ] Rate limiting configured
+- [ ] Sensitive data masked in logs
+- [ ] Audit logging implemented
+- [ ] Incident response plan documented
+
+---
+
+## Additional Resources
+
+- [Twilio Security Best Practices](https://www.twilio.com/docs/security)
+- [SendGrid Security Documentation](https://docs.sendgrid.com/for-developers/security)
+- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
+- [GDPR Compliance Guide](https://gdpr-info.eu/)
+- [TCPA SMS Compliance](https://www.fcc.gov/consumers/guides-and-resources-related-sms-texts)
+- [CAN-SPAM Compliance](https://www.ftc.gov/business-guidance/resources/can-spam-act-compliance-guide-business)
+
+---
+
+## Reporting Security Issues
+
+If you discover a security vulnerability in xTwilio, please email security@xenterprises.com instead of using the issue tracker. Please do not disclose the vulnerability publicly until it has been addressed.