@marvalt/madapter 2.1.0 → 2.2.1

package/templates/MAUTIC_SECURITY.md

@@ -0,0 +1,308 @@
+# Mautic Integration Security Hardening Guide
+
+**Auto-generated by @marvalt/madapter**
+
+This guide helps you secure your Mautic integration using Cloudflare's security features and best practices.
+
+---
+
+## 🔒 Security Checklist
+
+### ✅ Phase 1: Essential (Before Production)
+
+Complete these steps before deploying to production:
+
+- [ ] **1. Enable Turnstile (Bot Protection)**
+  - Sign up: https://dash.cloudflare.com/?to=/:account/turnstile
+  - Get your site key and secret key
+  - Add to `.env`:
+    ```bash
+    VITE_TURNSTILE_SITE_KEY=your_site_key_here
+    ```
+  - Add to `.env.local`:
+    ```bash
+    VITE_TURNSTILE_SECRET_KEY=your_secret_key_here
+    ```
+  - Turnstile will automatically protect all Mautic form submissions
+
+- [ ] **2. Configure Allowed Origins**
+  - Add to `.env`:
+    ```bash
+    VITE_ALLOWED_ORIGINS=https://your-app.pages.dev,https://your-custom-domain.com
+    ```
+  - This prevents unauthorized websites from using your API endpoint
+  - Use comma-separated list for multiple domains
+
+- [ ] **3. Enable Cloudflare Bot Fight Mode**
+  - Go to: Cloudflare Dashboard → Your Site → Security → Bots
+  - Toggle "Bot Fight Mode" to ON (Free tier)
+  - Automatically blocks known bad bots
+
+- [ ] **4. Configure Mautic Trusted Domains**
+  - Go to: Mautic → Settings → Configuration → System Settings
+  - Find "Trusted Domains" section
+  - Add your domains (one per line):
+    ```
+    your-app.pages.dev
+    your-custom-domain.com
+    localhost:8080
+    ```
+  - Save configuration
+
+- [ ] **5. Set Up Cloudflare Access for Mautic**
+  - Protect your Mautic instance behind Cloudflare Access
+  - Dashboard: https://dash.cloudflare.com/?to=/:account/access
+  - Create a Service Token for your application
+  - Add credentials to `.env.local`:
+    ```bash
+    VITE_CF_ACCESS_CLIENT_ID=your_client_id
+    VITE_CF_ACCESS_CLIENT_SECRET=your_client_secret
+    ```
+
+---
+
+### 🔥 Phase 2: Enhanced (After Launch)
+
+Implement these after your initial deployment:
+
+- [ ] **6. Add WAF Rate Limiting Rules**
+  - Go to: Cloudflare Dashboard → Security → WAF → Rate limiting rules
+  - Create new rule:
+    - **Rule name**: "Mautic Form Submission Limit"
+    - **If incoming requests match**: 
+      - URI Path equals `/api/mautic-submit`
+      - Method equals `POST`
+    - **Then**: Rate limit
+    - **Requests**: 10 requests per 1 minute
+    - **Action**: Block
+  - Save and deploy
+
+- [ ] **7. Enable Super Bot Fight Mode** (Requires Pro plan - $20/mo)
+  - Go to: Security → Bots
+  - Upgrade to Pro plan
+  - Enable "Super Bot Fight Mode"
+  - Advanced bot detection with machine learning
+
+- [ ] **8. Set Up Monitoring and Alerts**
+  - Go to: Analytics → Security
+  - Monitor blocked requests and bot traffic
+  - Set up email notifications:
+    - Notifications → Add
+    - Select "Security Events"
+    - Configure threshold (e.g., >100 blocked requests/hour)
+
+---
+
+### 💎 Phase 3: Advanced (Production Scale)
+
+For high-traffic or high-value applications:
+
+- [ ] **9. Custom WAF Rules**
+  - **Block specific countries** (if needed):
+    ```
+    (ip.geoip.country in {"CN" "RU"}) and 
+    (http.request.uri.path contains "/api/mautic-submit")
+    → Block
+    ```
+  
+  - **Challenge suspicious user agents**:
+    ```
+    (http.user_agent contains "curl" or 
+     http.user_agent contains "python" or
+     http.user_agent contains "bot") and
+    (http.request.uri.path eq "/api/mautic-submit")
+    → Managed Challenge
+    ```
+
+- [ ] **10. Implement Per-Form Rate Limiting**
+  - Use Cloudflare Workers KV for custom rate limiting
+  - Track submissions per IP per form ID
+  - Prevent targeted abuse of specific forms
+
+- [ ] **11. Enable Cloudflare Logs** (Business plan+)
+  - Full request logging for forensics
+  - Integrate with SIEM tools
+  - Long-term security analytics
+
+---
+
+## 📋 Environment Variables Reference
+
+### Required Variables
+
+**In `.env` (non-sensitive):**
+```bash
+# Mautic instance URL
+VITE_MAUTIC_URL=https://your-mautic-instance.com
+
+# Allowed origins (comma-separated)
+VITE_ALLOWED_ORIGINS=https://your-app.pages.dev,https://your-domain.com
+
+# Turnstile site key (public)
+VITE_TURNSTILE_SITE_KEY=0x4AAA...
+```
+
+**In `.env.local` (secrets - never commit!):**
+```bash
+# Mautic OAuth2 credentials
+VITE_MAUTIC_API_PUBLIC_KEY=your_oauth_client_id
+VITE_MAUTIC_API_SECRET_KEY=your_oauth_client_secret
+
+# Turnstile secret key
+VITE_TURNSTILE_SECRET_KEY=0x4BBB...
+
+# Cloudflare Access (optional)
+VITE_CF_ACCESS_CLIENT_ID=your_access_client_id
+VITE_CF_ACCESS_CLIENT_SECRET=your_access_client_secret
+```
+
+---
+
+## 🔧 Testing Your Security
+
+### 1. Test Turnstile Protection
+```bash
+# Should work (with valid Turnstile token)
+curl -X POST https://your-app.pages.dev/api/mautic-submit?endpoint=/form/submit \
+  -H "Origin: https://your-app.pages.dev" \
+  -H "cf-turnstile-response: valid_token_here"
+
+# Should fail (missing Turnstile token)
+curl -X POST https://your-app.pages.dev/api/mautic-submit?endpoint=/form/submit \
+  -H "Origin: https://your-app.pages.dev"
+# Expected: 403 Forbidden
+```
+
+### 2. Test Origin Validation
+```bash
+# Should fail (unauthorized origin)
+curl -X POST https://your-app.pages.dev/api/mautic-submit?endpoint=/form/submit \
+  -H "Origin: https://malicious-site.com"
+# Expected: 403 Forbidden
+```
+
+### 3. Test Endpoint Whitelisting
+```bash
+# Should fail (unauthorized endpoint)
+curl https://your-app.pages.dev/api/mautic-submit?endpoint=/api/contacts \
+  -H "Origin: https://your-app.pages.dev"
+# Expected: 403 Forbidden
+```
+
+### 4. Test Rate Limiting
+Submit a form 15 times rapidly - should be blocked after 10 submissions.
+
+---
+
+## 📊 Security Monitoring
+
+### Regular Checks
+
+**Daily:**
+- Check Cloudflare Analytics → Security Events
+- Review blocked requests and patterns
+
+**Weekly:**
+- Review Mautic form submissions for spam
+- Check for unusual traffic patterns
+- Verify Turnstile is working (check solve rate)
+
+**Monthly:**
+- Review and update allowed origins
+- Audit Cloudflare Access logs
+- Update WAF rules based on threats
+
+### Key Metrics
+
+- **Bot Score**: Should be mostly 1-30 (humans)
+- **Blocked Requests**: <5% of total traffic
+- **Turnstile Solve Rate**: >95%
+- **False Positives**: <1%
+
+---
+
+## 🆘 Troubleshooting
+
+### "Verification failed" Error
+
+**Symptoms:** Form submission fails with "Bot verification failed"
+
+**Solutions:**
+1. Check Turnstile secret key in `.env.local`
+2. Verify site key matches in Cloudflare dashboard
+3. Check browser console for Turnstile errors
+4. Ensure Turnstile script loads (check network tab)
+
+### "Forbidden origin" Error
+
+**Symptoms:** Form submission fails with "Forbidden origin"
+
+**Solutions:**
+1. Add your domain to `VITE_ALLOWED_ORIGINS` in `.env`
+2. Check for typos (`https://` vs `http://`)
+3. Verify domain matches exactly (including subdomain)
+4. Restart dev server after changing `.env`
+
+### "Forbidden endpoint" Error
+
+**Symptoms:** API calls fail with "Forbidden endpoint"
+
+**Solutions:**
+1. Only `/form/submit` endpoints are allowed
+2. Check endpoint format in request
+3. Verify you're not trying to access other Mautic APIs
+
+### Forms Not Submitting
+
+**Symptoms:** Form submission hangs or fails silently
+
+**Solutions:**
+1. Check browser console for errors
+2. Verify Mautic OAuth credentials in `.env.local`
+3. Check Cloudflare Access service token
+4. Verify Mautic instance is accessible
+5. Check Cloudflare Pages Function logs
+
+---
+
+## 📚 Additional Resources
+
+- **Cloudflare Turnstile**: https://developers.cloudflare.com/turnstile/
+- **Cloudflare Access**: https://developers.cloudflare.com/cloudflare-one/identity/service-tokens/
+- **Cloudflare WAF**: https://developers.cloudflare.com/waf/
+- **Mautic API**: https://developer.mautic.org/
+- **@marvalt/madapter**: https://github.com/MarVAlt/madapter
+
+---
+
+## 🎯 Security Level Assessment
+
+After completing each phase:
+
+| Phase | Protection Level | Suitable For |
+|-------|-----------------|--------------|
+| **Phase 1** | 85-90% | MVP, Small apps |
+| **Phase 2** | 95-98% | Production apps |
+| **Phase 3** | 99%+ | Enterprise, High-value |
+
+---
+
+## ✅ Quick Start Checklist
+
+For immediate deployment, complete these minimum steps:
+
+1. ✅ Add `VITE_ALLOWED_ORIGINS` to `.env`
+2. ✅ Enable Cloudflare Bot Fight Mode
+3. ✅ Configure Mautic Trusted Domains
+4. ✅ Set up Turnstile (get keys, add to env)
+5. ✅ Test form submission
+
+**Time required:** ~15 minutes  
+**Security level achieved:** Good (85-90%)
+
+---
+
+**Need help?** Check the troubleshooting section or open an issue on GitHub.
+
+**Last updated:** Auto-generated on package installation
+