Initial commit

2025-11-29 18:18:15 +08:00
commit e85b8b73e8
9 changed files with 1928 additions and 0 deletions
--- a/skills/cloudflare-troubleshooting/references/api_overview.md
+++ b/skills/cloudflare-troubleshooting/references/api_overview.md
@@ -0,0 +1,538 @@
+# Cloudflare API Overview
+
+## Authentication
+
+### Global API Key (used in examples)
+```bash
+curl -X GET "https://api.cloudflare.com/client/v4/..." \
+  -H "X-Auth-Email: user@example.com" \
+  -H "X-Auth-Key: abc123..."
+```
+
+### API Token (recommended for production)
+```bash
+curl -X GET "https://api.cloudflare.com/client/v4/..." \
+  -H "Authorization: Bearer <token>"
+```
+
+## Response Format
+
+All API responses follow this structure:
+```json
+{
+  "success": true/false,
+  "errors": [],
+  "messages": [],
+  "result": { ... },
+  "result_info": { ... }
+}
+```
+
+Always check `success` field before processing `result`.
+
+## Core Endpoints by Category
+
+### Zone Management
+
+**List zones:**
+```bash
+GET /zones?name=<domain>
+```
+Returns zone information including `id`, `name`, `status`, `name_servers`
+
+**Get zone details:**
+```bash
+GET /zones/{zone_id}
+```
+
+**Get all zone settings:**
+```bash
+GET /zones/{zone_id}/settings
+```
+Returns all configurable settings for the zone
+
+### SSL/TLS
+
+**Get SSL mode:**
+```bash
+GET /zones/{zone_id}/settings/ssl
+```
+Result: `{"value": "flexible"|"full"|"strict"|"off"}`
+
+**Update SSL mode:**
+```bash
+PATCH /zones/{zone_id}/settings/ssl
+Content-Type: application/json
+{"value": "full"}
+```
+
+**Get Always Use HTTPS:**
+```bash
+GET /zones/{zone_id}/settings/always_use_https
+```
+
+**Update Always Use HTTPS:**
+```bash
+PATCH /zones/{zone_id}/settings/always_use_https
+{"value": "on"|"off"}
+```
+
+**List SSL certificates:**
+```bash
+GET /zones/{zone_id}/ssl/certificate_packs
+```
+
+**Get SSL verification details:**
+```bash
+GET /zones/{zone_id}/ssl/verification
+```
+
+**Get SSL settings (universal, dedicated, etc):**
+```bash
+GET /zones/{zone_id}/ssl/analyze
+```
+
+**TLS 1.3 setting:**
+```bash
+GET /zones/{zone_id}/settings/tls_1_3
+PATCH /zones/{zone_id}/settings/tls_1_3
+{"value": "on"|"off"|"zrt"}
+```
+
+**Minimum TLS version:**
+```bash
+GET /zones/{zone_id}/settings/min_tls_version
+PATCH /zones/{zone_id}/settings/min_tls_version
+{"value": "1.0"|"1.1"|"1.2"|"1.3"}
+```
+
+### DNS Records
+
+**List DNS records:**
+```bash
+GET /zones/{zone_id}/dns_records
+```
+Returns array of DNS records with type, name, content, proxied status, TTL
+
+**Filter by type:**
+```bash
+GET /zones/{zone_id}/dns_records?type=A
+GET /zones/{zone_id}/dns_records?type=CNAME
+```
+
+**Get specific record:**
+```bash
+GET /zones/{zone_id}/dns_records/{record_id}
+```
+
+**Create DNS record:**
+```bash
+POST /zones/{zone_id}/dns_records
+{
+  "type": "A",
+  "name": "example.com",
+  "content": "192.0.2.1",
+  "ttl": 3600,
+  "proxied": true
+}
+```
+
+**Update DNS record:**
+```bash
+PATCH /zones/{zone_id}/dns_records/{record_id}
+{"proxied": true}
+```
+
+**Delete DNS record:**
+```bash
+DELETE /zones/{zone_id}/dns_records/{record_id}
+```
+
+**DNSSEC status:**
+```bash
+GET /zones/{zone_id}/dnssec
+```
+
+### Page Rules
+
+**List page rules:**
+```bash
+GET /zones/{zone_id}/pagerules
+```
+
+**Get specific page rule:**
+```bash
+GET /zones/{zone_id}/pagerules/{rule_id}
+```
+
+**Create page rule:**
+```bash
+POST /zones/{zone_id}/pagerules
+{
+  "targets": [{"target": "url", "constraint": {"operator": "matches", "value": "*example.com/*"}}],
+  "actions": [{"id": "always_use_https"}],
+  "priority": 1,
+  "status": "active"
+}
+```
+
+**Update page rule:**
+```bash
+PATCH /zones/{zone_id}/pagerules/{rule_id}
+```
+
+**Delete page rule:**
+```bash
+DELETE /zones/{zone_id}/pagerules/{rule_id}
+```
+
+### Cache
+
+**Purge everything:**
+```bash
+POST /zones/{zone_id}/purge_cache
+{"purge_everything": true}
+```
+
+**Purge by URL:**
+```bash
+POST /zones/{zone_id}/purge_cache
+{"files": ["https://example.com/style.css", "https://example.com/script.js"]}
+```
+
+**Purge by tag:**
+```bash
+POST /zones/{zone_id}/purge_cache
+{"tags": ["tag1", "tag2"]}
+```
+
+**Purge by host:**
+```bash
+POST /zones/{zone_id}/purge_cache
+{"hosts": ["example.com", "www.example.com"]}
+```
+
+**Cache settings:**
+```bash
+GET /zones/{zone_id}/settings/cache_level
+GET /zones/{zone_id}/settings/browser_cache_ttl
+GET /zones/{zone_id}/settings/development_mode
+```
+
+### Firewall
+
+**List firewall rules:**
+```bash
+GET /zones/{zone_id}/firewall/rules
+```
+
+**List WAF rules:**
+```bash
+GET /zones/{zone_id}/firewall/waf/packages
+GET /zones/{zone_id}/firewall/waf/packages/{package_id}/rules
+```
+
+**IP Access Rules:**
+```bash
+GET /zones/{zone_id}/firewall/access_rules/rules
+POST /zones/{zone_id}/firewall/access_rules/rules
+{
+  "mode": "block"|"challenge"|"whitelist",
+  "configuration": {"target": "ip", "value": "192.0.2.1"},
+  "notes": "Blocked malicious IP"
+}
+```
+
+**Rate limiting:**
+```bash
+GET /zones/{zone_id}/rate_limits
+POST /zones/{zone_id}/rate_limits
+```
+
+### Analytics
+
+**Get analytics:**
+```bash
+GET /zones/{zone_id}/analytics/dashboard
+```
+
+**Traffic analytics:**
+```bash
+GET /zones/{zone_id}/analytics/colos
+```
+
+**DNS analytics:**
+```bash
+GET /zones/{zone_id}/dns_analytics/report
+```
+
+### Load Balancers
+
+**List load balancers:**
+```bash
+GET /zones/{zone_id}/load_balancers
+```
+
+**Get load balancer details:**
+```bash
+GET /zones/{zone_id}/load_balancers/{lb_id}
+```
+
+**List pools:**
+```bash
+GET /accounts/{account_id}/load_balancers/pools
+```
+
+**List monitors:**
+```bash
+GET /accounts/{account_id}/load_balancers/monitors
+```
+
+### Workers & Routes
+
+**List worker routes:**
+```bash
+GET /zones/{zone_id}/workers/routes
+```
+
+**List worker scripts:**
+```bash
+GET /accounts/{account_id}/workers/scripts
+```
+
+### Settings (Other Common)
+
+**Development mode:**
+```bash
+GET /zones/{zone_id}/settings/development_mode
+PATCH /zones/{zone_id}/settings/development_mode
+{"value": "on"|"off"}
+```
+
+**Security level:**
+```bash
+GET /zones/{zone_id}/settings/security_level
+PATCH /zones/{zone_id}/settings/security_level
+{"value": "off"|"essentially_off"|"low"|"medium"|"high"|"under_attack"}
+```
+
+**Rocket Loader:**
+```bash
+GET /zones/{zone_id}/settings/rocket_loader
+PATCH /zones/{zone_id}/settings/rocket_loader
+{"value": "on"|"off"}
+```
+
+**Auto minify:**
+```bash
+GET /zones/{zone_id}/settings/minify
+PATCH /zones/{zone_id}/settings/minify
+{"value": {"css": "on", "html": "on", "js": "on"}}
+```
+
+**Brotli compression:**
+```bash
+GET /zones/{zone_id}/settings/brotli
+```
+
+**HTTP/2:**
+```bash
+GET /zones/{zone_id}/settings/http2
+```
+
+**HTTP/3 (QUIC):**
+```bash
+GET /zones/{zone_id}/settings/http3
+```
+
+**IPv6:**
+```bash
+GET /zones/{zone_id}/settings/ipv6
+```
+
+**Opportunistic Encryption:**
+```bash
+GET /zones/{zone_id}/settings/opportunistic_encryption
+```
+
+**Automatic HTTPS Rewrites:**
+```bash
+GET /zones/{zone_id}/settings/automatic_https_rewrites
+PATCH /zones/{zone_id}/settings/automatic_https_rewrites
+{"value": "on"|"off"}
+```
+
+## Learning New Endpoints
+
+### Method 1: List All Settings
+```bash
+curl -s -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/settings" \
+  -H "X-Auth-Email: email" \
+  -H "X-Auth-Key: key" | jq '.result[] | {id, value}'
+```
+
+This returns all available settings with current values. Use setting `id` to construct endpoint:
+`/zones/{zone_id}/settings/{id}`
+
+### Method 2: Cloudflare API Docs
+
+Browse official API reference: https://developers.cloudflare.com/api/
+
+**Structure:**
+- Operations organized by product/feature
+- Each operation shows:
+  - HTTP method and endpoint
+  - Required/optional parameters
+  - Request body schema
+  - Response schema
+  - Example requests
+
+**Search strategy:**
+1. Identify feature/product (SSL, DNS, Cache, etc.)
+2. Find relevant operations (List, Get, Create, Update, Delete)
+3. Check request schema for required fields
+4. Test with GET before making changes
+
+### Method 3: Explore API Interactively
+
+**Pattern:**
+1. Start with zone info to understand structure
+2. List resources: `GET /zones/{zone_id}/{resource_type}`
+3. Get specific item: `GET /zones/{zone_id}/{resource_type}/{id}`
+4. Check available operations in docs
+5. Make changes: `PATCH/POST/DELETE`
+
+**Example exploration for unknown feature:**
+```bash
+# 1. Check if endpoint exists
+curl -I "https://api.cloudflare.com/client/v4/zones/{zone_id}/feature_name"
+
+# 2. Try listing (if collection)
+curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/feature_name" \
+  -H "X-Auth-Email: email" \
+  -H "X-Auth-Key: key"
+
+# 3. Examine response structure
+# 4. Consult docs for modification operations
+```
+
+## Error Handling
+
+Common error codes:
+- 400: Bad request (check request format)
+- 401: Unauthorized (check API credentials)
+- 403: Forbidden (insufficient permissions)
+- 404: Not found (check zone_id or resource_id)
+- 429: Rate limit exceeded (wait before retrying)
+- 500: Server error (Cloudflare issue, retry later)
+
+**Error response structure:**
+```json
+{
+  "success": false,
+  "errors": [
+    {
+      "code": 1234,
+      "message": "Error description"
+    }
+  ],
+  "messages": [],
+  "result": null
+}
+```
+
+## Rate Limits
+
+- Free tier: ~1200 requests per 5 minutes
+- Paid tiers: Higher limits based on plan
+- If rate limited (429), back off exponentially
+
+## Best Practices
+
+1. **Use jq for readability:**
+   ```bash
+   curl ... | jq '.result'
+   ```
+
+2. **Extract specific fields:**
+   ```bash
+   curl ... | jq '.result.value'
+   curl ... | jq '.result[] | {id, name, value}'
+   ```
+
+3. **Check success before processing:**
+   ```bash
+   response=$(curl ...)
+   success=$(echo "$response" | jq -r '.success')
+   if [ "$success" = "true" ]; then
+     echo "$response" | jq '.result'
+   else
+     echo "$response" | jq '.errors'
+   fi
+   ```
+
+4. **Store zone_id for reuse:**
+   ```bash
+   zone_id=$(curl ... | jq -r '.result[0].id')
+   ```
+
+5. **Test with GET first:**
+   Before modifying configuration, always GET to see current state
+
+## Common Investigation Patterns
+
+### Pattern 1: Settings Investigation
+```bash
+# Get all settings
+curl -X GET "/zones/{zone_id}/settings" | jq '.result[]'
+
+# Filter specific settings
+curl -X GET "/zones/{zone_id}/settings" | jq '.result[] | select(.id | contains("ssl"))'
+```
+
+### Pattern 2: Resource Listing + Details
+```bash
+# List resources
+curl -X GET "/zones/{zone_id}/dns_records" | jq '.result[] | {id, name, type}'
+
+# Get specific resource
+record_id="..."
+curl -X GET "/zones/{zone_id}/dns_records/$record_id" | jq '.'
+```
+
+### Pattern 3: Multi-Setting Check
+```bash
+# Check related settings in parallel
+curl ... /settings/ssl &
+curl ... /settings/always_use_https &
+curl ... /pagerules &
+wait
+```
+
+### Pattern 4: Change + Verify
+```bash
+# Make change
+curl -X PATCH "/zones/{zone_id}/settings/ssl" -d '{"value":"full"}'
+
+# Verify change applied
+curl -X GET "/zones/{zone_id}/settings/ssl" | jq '.result.value'
+```
+
+## Account-Level vs Zone-Level
+
+Some resources are account-level, not zone-level:
+
+**Account-level:**
+- Load balancer pools/monitors: `/accounts/{account_id}/load_balancers/...`
+- Workers scripts: `/accounts/{account_id}/workers/...`
+- Access policies: `/accounts/{account_id}/access/...`
+
+**Zone-level:**
+- DNS records: `/zones/{zone_id}/dns_records`
+- SSL settings: `/zones/{zone_id}/settings/ssl`
+- Page rules: `/zones/{zone_id}/pagerules`
+
+Get account_id from zone info:
+```bash
+curl -X GET "/zones?name=example.com" | jq '.result[0].account.id'
+```
--- a/skills/cloudflare-troubleshooting/references/common_issues.md
+++ b/skills/cloudflare-troubleshooting/references/common_issues.md
@@ -0,0 +1,261 @@
+# Common Cloudflare Issues and Solutions
+
+## Redirect Loop Errors (ERR_TOO_MANY_REDIRECTS)
+
+### Symptom
+Browser displays "This page isn't working" or "ERR_TOO_MANY_REDIRECTS"
+
+### Common Causes
+
+#### 1. SSL Mode Mismatch (Most Common)
+**Scenario:** Origin server enforces HTTPS, but Cloudflare SSL mode is "Flexible"
+
+**Explanation:**
+- Browser → HTTPS → Cloudflare
+- Cloudflare → HTTP → Origin Server (because of Flexible mode)
+- Origin Server → Redirects to HTTPS (because it enforces HTTPS)
+- Infinite loop
+
+**Affected Platforms:**
+- GitHub Pages
+- Netlify
+- Vercel
+- Heroku
+- Most modern hosting platforms
+
+**Solution:**
+Change SSL mode from "Flexible" to "Full" or "Full (strict)"
+
+```bash
+# Diagnose
+python scripts/check_cloudflare_config.py example.com user@example.com API_KEY
+
+# Fix
+python scripts/fix_ssl_mode.py example.com user@example.com API_KEY full --purge-cache
+```
+
+#### 2. Conflicting Page Rules
+**Scenario:** Multiple redirect rules that conflict with each other
+
+**Solution:**
+- Review Page Rules in Cloudflare Dashboard
+- Remove conflicting "Always Use HTTPS" or "Forwarding URL" rules
+- Ensure redirect rules don't create loops
+
+#### 3. Origin Server Misconfiguration
+**Scenario:** Origin server has incorrect redirect rules in .htaccess or nginx config
+
+**Solution:**
+- Check origin server configuration
+- Verify redirects don't conflict with Cloudflare settings
+- Test direct origin access (bypass Cloudflare)
+
+### Resolution Steps
+
+1. **Check SSL mode:**
+   ```bash
+   curl -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID/settings/ssl" \
+     -H "X-Auth-Email: email" \
+     -H "X-Auth-Key: key"
+   ```
+
+2. **Fix SSL mode if needed:**
+   ```bash
+   python scripts/fix_ssl_mode.py domain.com email API_KEY full
+   ```
+
+3. **Purge cache:**
+   ```bash
+   curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/purge_cache" \
+     -H "X-Auth-Email: email" \
+     -H "X-Auth-Key: key" \
+     -d '{"purge_everything":true}'
+   ```
+
+4. **Clear browser cache or use incognito mode**
+
+---
+
+## DNS Resolution Issues
+
+### Symptom
+Website not accessible or showing old content
+
+### Common Causes
+
+#### 1. DNS Not Propagated
+**Solution:** Wait 24-48 hours for full DNS propagation
+
+Check propagation:
+```bash
+dig domain.com
+nslookup domain.com
+```
+
+#### 2. Incorrect DNS Records
+**Solution:**
+- Verify A/AAAA/CNAME records point to correct IPs
+- For GitHub Pages: Use A records to GitHub IPs or CNAME to username.github.io
+- Ensure "Proxied" status matches requirements
+
+#### 3. DNSSEC Issues
+**Solution:**
+- Check DNSSEC status in Cloudflare Dashboard
+- Verify DS records at registrar match Cloudflare's DNSSEC settings
+
+---
+
+## SSL/TLS Certificate Errors
+
+### Symptom
+"Your connection is not private" or "NET::ERR_CERT_COMMON_NAME_INVALID"
+
+### Common Causes
+
+#### 1. Universal SSL Certificate Provisioning Delay
+**Solution:** Wait 15-30 minutes for Cloudflare to provision certificate
+
+#### 2. CAA Records Blocking Certificate Issuance
+**Solution:**
+- Check CAA records
+- Ensure CAA allows Let's Encrypt: `letsencrypt.org` or Cloudflare CAs
+
+#### 3. Full (Strict) Mode with Invalid Origin Certificate
+**Solution:**
+- Use "Full" mode instead of "Full (strict)" if origin cert is self-signed
+- Or install valid certificate on origin server
+
+---
+
+## Performance Issues
+
+### Symptom
+Slow page load times despite using Cloudflare
+
+### Common Causes
+
+#### 1. Cache Not Configured
+**Solution:**
+- Enable Auto Minify (JS, CSS, HTML)
+- Set up Page Rules for cache levels
+- Configure Browser Cache TTL
+
+#### 2. Large Assets Not Optimized
+**Solution:**
+- Enable Cloudflare Image Optimization
+- Use WebP format
+- Implement lazy loading
+
+#### 3. Too Many Uncached Requests
+**Solution:**
+- Review cache analytics
+- Add cache rules for static assets
+- Use Cloudflare Workers for dynamic caching
+
+---
+
+## Access Denied / 403 Errors
+
+### Symptom
+"Error 1020: Access Denied" or generic 403
+
+### Common Causes
+
+#### 1. Firewall Rules Blocking Traffic
+**Solution:**
+- Review Firewall Rules in Security → WAF
+- Check IP Access Rules
+- Verify Managed Rulesets aren't too strict
+
+#### 2. Rate Limiting
+**Solution:**
+- Check Rate Limiting rules
+- Adjust thresholds if legitimate traffic is blocked
+
+#### 3. Browser Integrity Check
+**Solution:**
+- Disable "Browser Integrity Check" if needed
+- Found in: Security → Settings
+
+---
+
+## Origin Server Errors (502/503/504)
+
+### Symptom
+"502 Bad Gateway" or "504 Gateway Timeout"
+
+### Common Causes
+
+#### 1. Origin Server Down
+**Solution:**
+- Verify origin server is running
+- Check origin server logs
+- Test direct IP access
+
+#### 2. Origin SSL Certificate Invalid (Full Strict mode)
+**Solution:**
+- Switch to "Full" mode temporarily
+- Fix origin certificate
+- Or use Cloudflare Origin Certificate
+
+#### 3. Timeout Issues
+**Solution:**
+- Increase origin server timeout settings
+- Optimize slow queries/code
+- Consider using Cloudflare Workers for timeouts
+
+---
+
+## Page Rules Not Working
+
+### Symptom
+Page Rules don't seem to apply
+
+### Common Causes
+
+#### 1. Rule Order
+**Solution:** Page Rules are executed top-to-bottom; reorder if needed
+
+#### 2. Pattern Matching Issues
+**Solution:**
+- Use `*` for wildcards correctly
+- Test patterns: `example.com/*` vs `*example.com/*`
+
+#### 3. Cache Already Set
+**Solution:** Purge cache after creating/modifying Page Rules
+
+---
+
+## Troubleshooting Workflow
+
+### Step 1: Identify the Issue
+- Collect error messages and codes
+- Note when issue started
+- Check if issue is intermittent or consistent
+
+### Step 2: Check Cloudflare Status
+- Visit https://www.cloudflarestatus.com
+- Verify no ongoing incidents
+
+### Step 3: Run Diagnostics
+```bash
+python scripts/check_cloudflare_config.py domain.com email API_KEY
+```
+
+### Step 4: Review Recent Changes
+- Check Cloudflare Audit Log
+- Review recent DNS/SSL/Page Rule changes
+
+### Step 5: Test Bypass
+- Temporarily set DNS to "DNS Only" (grey cloud)
+- Test if issue persists without Cloudflare
+
+### Step 6: Apply Fixes
+- Implement specific solutions based on diagnosis
+- Purge cache after changes
+- Test in incognito/private mode
+
+### Step 7: Monitor
+- Verify fix works consistently
+- Check analytics for any anomalies
+- Document solution for future reference
--- a/skills/cloudflare-troubleshooting/references/ssl_modes.md
+++ b/skills/cloudflare-troubleshooting/references/ssl_modes.md
@@ -0,0 +1,246 @@
+# Cloudflare SSL/TLS Modes Explained
+
+## Overview
+
+Cloudflare offers four SSL/TLS encryption modes that determine how traffic is encrypted between visitors, Cloudflare, and your origin server.
+
+```
+Visitor ←→ Cloudflare ←→ Origin Server
+  [A]         [B]          [C]
+
+[A] Visitor to Cloudflare: Always HTTPS (handled by Cloudflare Universal SSL)
+[B] Cloudflare to Origin: Depends on SSL mode setting
+```
+
+## The Four SSL Modes
+
+### 1. Off (Not Recommended)
+
+**Encryption:**
+- Visitor → Cloudflare: HTTP (unencrypted)
+- Cloudflare → Origin: HTTP (unencrypted)
+
+**When to use:** Never. This disables HTTPS entirely.
+
+**Issues:**
+- Browser shows "Not Secure" warning
+- No encryption between visitor and Cloudflare
+- Vulnerable to man-in-the-middle attacks
+
+---
+
+### 2. Flexible
+
+**Encryption:**
+- Visitor → Cloudflare: HTTPS (encrypted)
+- Cloudflare → Origin: HTTP (unencrypted)
+
+**When to use:**
+- Origin server doesn't support HTTPS
+- Legacy systems without SSL certificates
+- Temporary solution during certificate setup
+
+**Issues:**
+- ⚠️ **CAUSES REDIRECT LOOPS** with origins that enforce HTTPS
+- Traffic between Cloudflare and origin is unencrypted
+- Not recommended for sensitive data
+
+**Common redirect loop scenario:**
+```
+1. Browser requests https://example.com
+2. Cloudflare receives HTTPS request
+3. Cloudflare forwards HTTP request to origin (because mode is Flexible)
+4. Origin server enforces HTTPS → redirects to https://example.com
+5. Back to step 1 → INFINITE LOOP
+```
+
+**Affected platforms:**
+- GitHub Pages
+- Netlify
+- Vercel
+- Heroku
+- Any platform that enforces HTTPS
+
+---
+
+### 3. Full (Recommended for Most Cases)
+
+**Encryption:**
+- Visitor → Cloudflare: HTTPS (encrypted)
+- Cloudflare → Origin: HTTPS (encrypted)
+
+**When to use:**
+- Origin server supports HTTPS (most modern hosting)
+- Self-signed certificates on origin
+- Default choice for GitHub Pages, Netlify, Vercel, etc.
+
+**Benefits:**
+- End-to-end encryption
+- No redirect loops with HTTPS-enforcing origins
+- Compatible with self-signed certificates
+
+**Important:**
+- Cloudflare does NOT validate origin certificate
+- Origin can use self-signed or expired certificates
+- Still provides encryption, just doesn't verify origin identity
+
+---
+
+### 4. Full (Strict) (Most Secure)
+
+**Encryption:**
+- Visitor → Cloudflare: HTTPS (encrypted)
+- Cloudflare → Origin: HTTPS (encrypted + validated)
+
+**When to use:**
+- Origin has valid SSL certificate from trusted CA
+- Maximum security requirements
+- Production environments with proper certificates
+
+**Requirements:**
+- Origin must have valid certificate from trusted CA
+- Certificate must not be expired
+- Certificate must match the domain
+
+**Benefits:**
+- Maximum security
+- Validates origin server identity
+- Prevents man-in-the-middle attacks between Cloudflare and origin
+
+**Issues if misconfigured:**
+- 526 error if origin certificate is invalid
+- 525 error if SSL handshake fails
+
+---
+
+## Decision Matrix
+
+| Origin Supports HTTPS? | Origin Certificate Valid? | Recommended Mode | Why |
+|------------------------|---------------------------|------------------|-----|
+| No | N/A | Flexible | Only option (but upgrade origin ASAP) |
+| Yes | Self-signed/Invalid | Full | Encrypts traffic, doesn't validate cert |
+| Yes | Valid from trusted CA | Full (Strict) | Maximum security |
+| Yes (enforced) | Any | Full or Full (Strict) | Prevents redirect loops |
+
+## Common Platforms and Recommended Modes
+
+| Platform | Enforces HTTPS? | Recommended Mode | Notes |
+|----------|-----------------|------------------|-------|
+| GitHub Pages | Yes | Full or Full (Strict) | Full (Strict) preferred |
+| Netlify | Yes | Full or Full (Strict) | Has valid certificates |
+| Vercel | Yes | Full or Full (Strict) | Has valid certificates |
+| Heroku | Yes | Full or Full (Strict) | Has valid certificates |
+| Custom VPS | Depends | Full (Strict) if possible | Install Let's Encrypt cert |
+| Shared Hosting | Varies | Check with host | Usually Full |
+| AWS CloudFront | Configurable | Full (Strict) | Use ACM certificates |
+
+## Troubleshooting SSL Mode Issues
+
+### Redirect Loop (ERR_TOO_MANY_REDIRECTS)
+
+**Cause:** SSL mode is "Flexible" but origin enforces HTTPS
+
+**Solution:**
+```bash
+# Check current mode
+curl -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID/settings/ssl" \
+  -H "X-Auth-Email: email" \
+  -H "X-Auth-Key: key"
+
+# Change to Full
+python scripts/fix_ssl_mode.py domain.com email API_KEY full --purge-cache
+```
+
+### Error 526 (Invalid SSL Certificate)
+
+**Cause:** Mode is "Full (Strict)" but origin certificate is invalid
+
+**Solutions:**
+1. Install valid certificate on origin (recommended)
+2. Switch to "Full" mode temporarily:
+   ```bash
+   python scripts/fix_ssl_mode.py domain.com email API_KEY full
+   ```
+3. Use Cloudflare Origin Certificate (free, only trusted by Cloudflare)
+
+### Error 525 (SSL Handshake Failed)
+
+**Cause:** Origin server SSL/TLS configuration issue
+
+**Solutions:**
+1. Check origin server SSL logs
+2. Verify origin supports TLS 1.2 or higher
+3. Ensure origin port 443 is open
+4. Check cipher suite compatibility
+
+## Best Practices
+
+### 1. Start with Full Mode
+When in doubt, use "Full" mode for origins that support HTTPS
+
+### 2. Upgrade to Full (Strict) When Possible
+Install proper certificates and use Full (Strict) for production
+
+### 3. Never Use Flexible for New Sites
+Flexible should only be used for legacy systems during migration
+
+### 4. Use Cloudflare Origin Certificates
+For custom origin servers, install Cloudflare Origin Certificates:
+- Free
+- Valid for 15 years
+- Trusted by Cloudflare (enables Full Strict mode)
+- Generate at: SSL/TLS → Origin Server → Create Certificate
+
+### 5. Monitor SSL Errors
+Set up alerts for SSL-related errors (525, 526) in Cloudflare Analytics
+
+### 6. Test After Changes
+- Clear browser cache
+- Test in incognito mode
+- Purge Cloudflare cache
+- Wait 30-60 seconds for edge server updates
+
+## Additional Security Settings
+
+### Always Use HTTPS
+- Redirects all HTTP requests to HTTPS
+- Located: SSL/TLS → Edge Certificates
+- Usually enabled by default
+- Can cause loops if misconfigured with Page Rules
+
+### HTTP Strict Transport Security (HSTS)
+- Forces browsers to always use HTTPS
+- Can't easily revert (browsers cache for months)
+- Enable only when HTTPS is stable
+- Located: SSL/TLS → Edge Certificates
+
+### Minimum TLS Version
+- Set to TLS 1.2 minimum (recommended)
+- TLS 1.3 for maximum security
+- Located: SSL/TLS → Edge Certificates
+
+### Opportunistic Encryption
+- Encrypts traffic when possible
+- Good for mixed content
+- Located: SSL/TLS → Edge Certificates
+
+## API Reference
+
+### Get SSL Mode
+```bash
+curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/settings/ssl" \
+  -H "X-Auth-Email: user@example.com" \
+  -H "X-Auth-Key: api_key" \
+  -H "Content-Type: application/json"
+```
+
+### Change SSL Mode
+```bash
+curl -X PATCH "https://api.cloudflare.com/client/v4/zones/{zone_id}/settings/ssl" \
+  -H "X-Auth-Email: user@example.com" \
+  -H "X-Auth-Key: api_key" \
+  -H "Content-Type: application/json" \
+  --data '{"value":"full"}'
+```
+
+Valid values: `off`, `flexible`, `full`, `strict`