@xenterprises/fastify-xstripe 1.0.0

package/SECURITY.md

@@ -0,0 +1,465 @@
+# Security Policy
+
+## Overview
+
+xStripe is a Fastify plugin for Stripe webhook handling. This document outlines the security considerations, best practices, and guidelines for using xStripe safely in production environments.
+
+## Security Model
+
+### What xStripe Does Safely
+- **Webhook Signature Verification** - All webhook requests verified against Stripe signature
+- **Request Validation** - Ensures only valid Stripe events are processed
+- **Isolated Handler Execution** - Each handler runs in isolated context
+- **Error Handling** - Errors don't expose sensitive data
+- **API Key Security** - Keys never logged or exposed in errors
+
+### Attack Surface
+The main security concerns are:
+
+1. **Webhook Signature Verification** - Ensuring authentic Stripe requests
+2. **Handler Code Injection** - Custom handlers with untrusted input
+3. **API Key Exposure** - Secure key management
+4. **Data Leakage** - Error messages revealing sensitive information
+5. **Idempotency** - Duplicate event handling
+
+## Security Guidelines
+
+### 1. Webhook Signature Verification
+
+**Current Implementation** ✅
+```javascript
+// Automatically verified by Stripe SDK
+const event = await stripe.webhooks.constructEvent(
+  body,
+  sig,
+  webhookSecret
+);
+```
+
+**Always Required**
+- Webhook secret must be set in production
+- Never skip signature verification
+- Logs indicate if verification is disabled
+
+**Best Practice**:
+```javascript
+await fastify.register(xStripe, {
+  apiKey: process.env.STRIPE_API_KEY,
+  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET, // Required
+  webhookPath: '/stripe/webhook',
+});
+```
+
+**Failure Handling**:
+```javascript
+fastify.setErrorHandler((error, request, reply) => {
+  if (error.code === 'SIGNATURE_VERIFY_FAILURE') {
+    // Log security event
+    fastify.log.warn('Invalid Stripe webhook signature');
+    reply.status(401).send({ error: 'Unauthorized' });
+  }
+});
+```
+
+---
+
+### 2. API Key Management
+
+**Risk**: Stripe API keys are highly sensitive credentials
+
+**Secure Practices**:
+```javascript
+// ✅ Use environment variables
+const apiKey = process.env.STRIPE_API_KEY;
+const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;
+
+// ✅ Rotate keys regularly
+// ✅ Use restricted API keys for specific operations
+// ✅ Monitor API key usage in Stripe Dashboard
+
+// ❌ Never hardcode credentials
+// ❌ Never commit credentials to git
+// ❌ Never log credentials
+```
+
+**Environment Variable Setup**:
+```bash
+# .env (NEVER commit this file)
+STRIPE_API_KEY=sk_live_xxxxx
+STRIPE_WEBHOOK_SECRET=whsec_xxxxx
+
+# .gitignore
+.env
+.env.local
+*.key
+```
+
+**Monitoring**:
+- Check Stripe Dashboard for suspicious API activity
+- Rotate keys if compromised
+- Use restricted API keys with specific scopes
+
+---
+
+### 3. Handler Code Security
+
+**Risk**: Custom handlers processing untrusted event data
+
+**Validation Pattern**:
+```javascript
+// ✅ Validate all event data
+const handler = async (event, fastify, stripe) => {
+  // Validate required fields
+  if (!event.data?.object?.id) {
+    throw new Error('Invalid event structure');
+  }
+
+  const customerId = event.data.object.customer;
+
+  // Verify customer exists and belongs to correct account
+  const customer = await stripe.customers.retrieve(customerId);
+  if (!customer) {
+    throw new Error('Customer not found');
+  }
+
+  // Process safely
+  await fastify.db.user.update({
+    where: { stripeCustomerId: customerId },
+    data: { subscriptionStatus: 'active' },
+  });
+};
+
+// ❌ Never trust event data blindly
+// ❌ Don't use event data in database queries without validation
+```
+
+**Error Handling**:
+```javascript
+// ✅ Catch errors in handlers
+try {
+  // Handler logic
+} catch (error) {
+  // Log full error internally
+  fastify.log.error(error);
+
+  // Return generic error to Stripe
+  reply.status(200).send({ received: true });
+
+  // Set up alerting for failures
+  await alerting.notify({
+    severity: 'high',
+    message: `Webhook handler failed: ${error.message}`,
+  });
+}
+
+// ❌ Don't expose error details to client
+// ❌ Don't return error messages in webhook response
+```
+
+---
+
+### 4. Idempotency & Duplicate Events
+
+**Risk**: Stripe might retry failed webhooks, causing duplicate processing
+
+**Best Practice - Idempotent Operations**:
+```javascript
+// ✅ Use event ID for deduplication
+const handler = async (event, fastify, stripe) => {
+  const eventId = event.id;
+
+  // Check if already processed
+  const processed = await fastify.db.webhookEvent.findUnique({
+    where: { stripeEventId: eventId },
+  });
+
+  if (processed) {
+    return; // Already handled, skip
+  }
+
+  // Process event
+  await processSubscription(event);
+
+  // Mark as processed
+  await fastify.db.webhookEvent.create({
+    data: {
+      stripeEventId: eventId,
+      type: event.type,
+      processedAt: new Date(),
+    },
+  });
+};
+```
+
+**Database Schema**:
+```javascript
+// Track processed events
+model WebhookEvent {
+  id String @id @default(cuid())
+  stripeEventId String @unique
+  type String
+  processedAt DateTime @default(now())
+}
+```
+
+---
+
+### 5. Error Handling
+
+**Risk**: Error messages could expose sensitive information
+
+**Secure Error Responses**:
+```javascript
+// ✅ Generic response to Stripe
+reply.status(200).send({ received: true });
+
+// ✅ Log detailed errors internally
+fastify.log.error('Handler failed:', {
+  eventId: event.id,
+  type: event.type,
+  error: error.message,
+  stack: error.stack,
+});
+
+// ✅ Alert on critical failures
+if (error.code === 'DATABASE_ERROR') {
+  await alerting.critical('Database failure in webhook handler');
+}
+
+// ❌ Never send error details in response
+// ❌ Never log API keys
+// ❌ Never expose stack traces to clients
+```
+
+---
+
+### 6. HTTP Endpoint Security
+
+**Webhook Endpoint Protection**:
+```javascript
+// Basic rate limiting
+import rateLimit from '@fastify/rate-limit';
+
+await fastify.register(rateLimit, {
+  max: 1000, // 1000 requests
+  timeWindow: '1 minute',
+});
+
+// Webhook-specific protection
+fastify.post('/stripe/webhook', {
+  config: {
+    rateLimit: {
+      max: 500, // Stripe sends frequently
+      timeWindow: '1 minute',
+    },
+  },
+}, async (request, reply) => {
+  // Handler
+});
+```
+
+**Input Validation**:
+```javascript
+// Validate Stripe signature header
+const sig = request.headers['stripe-signature'];
+if (!sig) {
+  return reply.status(401).send({ error: 'Missing signature' });
+}
+
+// Size limits
+const MAX_PAYLOAD = 1024 * 100; // 100KB
+if (request.rawBody.length > MAX_PAYLOAD) {
+  return reply.status(413).send({ error: 'Payload too large' });
+}
+```
+
+---
+
+### 7. Logging & Monitoring
+
+**Safe Logging**:
+```javascript
+// ✅ Log event IDs and types
+fastify.log.info('Processing webhook', {
+  eventId: event.id,
+  type: event.type,
+  timestamp: event.created,
+});
+
+// ✅ Log handler outcomes
+fastify.log.info('Webhook processed', {
+  eventId: event.id,
+  handler: handlerName,
+  duration: endTime - startTime,
+});
+
+// ❌ Never log sensitive data
+// ❌ Never log API keys
+// ❌ Never log customer financial info
+```
+
+**Monitoring Setup**:
+```javascript
+// Track success/failure rates
+const metrics = {
+  successCount: 0,
+  failureCount: 0,
+  lastEvent: null,
+};
+
+// Alert on failures
+if (handlerError) {
+  metrics.failureCount++;
+
+  if (metrics.failureCount > 5) {
+    await alerting.critical('High webhook failure rate');
+  }
+}
+```
+
+---
+
+### 8. Stripe Account Security
+
+**Best Practices**:
+- Enable 2FA on Stripe account
+- Use team and roles for access control
+- Rotate API keys periodically
+- Monitor API activity in dashboard
+- Use restricted API keys for webhooks
+- Review connected accounts regularly
+- Set up IP allowlisting if possible
+- Enable email notifications for key events
+
+**Webhook Settings**:
+- Only subscribe to necessary events
+- Use specific event types, not wildcards
+- Monitor webhook failures in dashboard
+- Test webhooks in test mode first
+- Keep webhook endpoint updated
+- Version your webhook handlers
+
+---
+
+### 9. Credential Rotation
+
+**Rotating Stripe Keys**:
+1. Generate new API key in Stripe Dashboard
+2. Update environment variable
+3. Restart application
+4. Verify new key works
+5. Delete old key in Stripe Dashboard
+
+**Time-based Rotation**:
+```bash
+# Rotate keys every 90 days
+0 0 1 */3 * /path/to/rotate-keys.sh
+```
+
+---
+
+### 10. Incident Response
+
+**If API Key is Compromised**:
+1. Immediately deactivate key in Stripe Dashboard
+2. Generate new key
+3. Update all applications
+4. Restart services
+5. Review API activity for unauthorized use
+6. Monitor account for suspicious activity
+
+**If Webhook Fails Repeatedly**:
+1. Check webhook endpoint is responding
+2. Verify signature secret is correct
+3. Review error logs
+4. Check for rate limiting
+5. Contact Stripe support if issue persists
+
+---
+
+## Security Checklist for Production
+
+- [ ] Webhook secret configured in environment
+- [ ] Stripe API key in environment variable (not hardcoded)
+- [ ] Handler validation for event data
+- [ ] Idempotency checks implemented
+- [ ] Error handling doesn't expose sensitive data
+- [ ] Logging doesn't include credentials
+- [ ] Rate limiting configured
+- [ ] HTTPS enforced for webhook endpoint
+- [ ] Database transactions for consistency
+- [ ] Monitoring and alerting set up
+- [ ] Backup/restore plan for webhook data
+- [ ] Incident response plan documented
+
+---
+
+## Dependencies Security
+
+### Stripe SDK
+- Keep stripe SDK updated
+- Monitor npm for security advisories
+- Test updates in staging first
+
+### Fastify
+- Keep Fastify updated
+- Enable security headers
+- Use official Fastify modules only
+
+```bash
+# Regular security checks
+npm audit
+npm audit fix
+
+# Check outdated packages
+npm outdated
+
+# Update with caution
+npm update --depth 3
+```
+
+---
+
+## Compliance
+
+### PCI Compliance
+- Never store raw card data
+- Use Stripe for payment processing
+- Don't log sensitive card information
+- Ensure HTTPS for all communication
+- Implement access controls
+
+### GDPR Compliance
+- Respect customer data privacy
+- Implement data retention policies
+- Provide data deletion on request
+- Document processing activities
+- Update privacy policy
+
+---
+
+## Additional Resources
+
+- [Stripe Security](https://stripe.com/docs/security)
+- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
+- [Node.js Security Best Practices](https://nodejs.org/en/docs/guides/security/)
+- [Fastify Security](https://www.fastify.io/docs/latest/Guides/Security/)
+
+---
+
+## Reporting Security Issues
+
+**Please do not open public GitHub/GitLab issues for security vulnerabilities.**
+
+Email security concerns to: [contact info when available]
+
+Include:
+- Description of vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if any)
+
+---
+
+**Last Updated**: 2024-12-29
+**Maintained By**: Tim Mushen