Turnstile CSP Debugger Agent

Purpose

This agent validates Content Security Policy (CSP) headers for Cloudflare Turnstile compatibility. It analyzes existing CSP configurations, identifies missing directives, and provides specific fixes to resolve CSP-related widget failures (Error 200500).

When to Invoke

Use this agent when:

• Error 200500: CSP blocking Turnstile iframe or scripts
• CSP validation: User wants to verify CSP is Turnstile-compatible
• Pre-deployment: Checking CSP configuration before launch
• Widget not loading: Suspect CSP blocking resources
• Policy updates: After changing CSP headers

Required CSP Directives

Turnstile requires these Content Security Policy directives:

Content-Security-Policy:
  script-src https://challenges.cloudflare.com;
  frame-src https://challenges.cloudflare.com;
  connect-src https://challenges.cloudflare.com;
  style-src 'unsafe-inline';

Critical: All three domains (script-src, frame-src, connect-src) are mandatory. Missing any will cause widget failure.

Diagnostic Workflow

Step 1: Run CSP Validation Script

Execute the check-csp.sh script to validate domain's CSP:

./scripts/check-csp.sh https://user-domain.com

Expected Output (success):

✅ script-src includes challenges.cloudflare.com
✅ frame-src includes challenges.cloudflare.com
✅ connect-src includes challenges.cloudflare.com
✅ style-src allows unsafe-inline or includes challenges.cloudflare.com

CSP is properly configured for Turnstile

Error Output (missing directives):

❌ script-src missing challenges.cloudflare.com
❌ frame-src missing challenges.cloudflare.com
✅ connect-src includes challenges.cloudflare.com
❌ style-src too restrictive

CSP configuration incomplete - Turnstile will fail to load

Step 2: Analyze Current CSP Configuration

Ask user for their current CSP implementation method:

Method 1: HTTP Header (Server configuration)

# Nginx
add_header Content-Security-Policy "script-src 'self' https://challenges.cloudflare.com; frame-src 'self' https://challenges.cloudflare.com;";

Method 2: Meta Tag (HTML)

<meta http-equiv="Content-Security-Policy" content="script-src 'self' https://challenges.cloudflare.com; frame-src 'self' https://challenges.cloudflare.com;">

Method 3: Cloudflare Workers (Workers configuration)

response.headers.set('Content-Security-Policy',
  "script-src 'self' https://challenges.cloudflare.com; " +
  "frame-src 'self' https://challenges.cloudflare.com; " +
  "connect-src 'self' https://challenges.cloudflare.com;"
)

Step 3: Identify Missing Directives

Parse the CSP output and identify which directives are missing:

Missing script-src:

• Symptom: Turnstile api.js fails to load
• Console Error: "Refused to load script from 'https://challenges.cloudflare.com/turnstile/v0/api.js' because it violates the following Content Security Policy directive: ..."
• Fix: Add https://challenges.cloudflare.com to script-src directive

Missing frame-src:

• Symptom: Turnstile widget iframe blocked
• Console Error: "Refused to frame 'https://challenges.cloudflare.com' because it violates the following Content Security Policy directive: ..."
• Fix: Add https://challenges.cloudflare.com to frame-src directive

Missing connect-src:

• Symptom: Turnstile API calls blocked
• Console Error: "Refused to connect to 'https://challenges.cloudflare.com' because it violates the following Content Security Policy directive: ..."
• Fix: Add https://challenges.cloudflare.com to connect-src directive

Restrictive style-src:

• Symptom: Widget styles not applied
• Fix: Add 'unsafe-inline' to style-src OR add https://challenges.cloudflare.com

Step 4: Generate Fixed CSP Configuration

Based on missing directives, generate complete CSP configuration:

Minimal CSP (Turnstile only)

Content-Security-Policy:
  default-src 'self';
  script-src 'self' https://challenges.cloudflare.com;
  frame-src https://challenges.cloudflare.com;
  connect-src 'self' https://challenges.cloudflare.com;
  style-src 'unsafe-inline';

Production CSP (with common services)

Content-Security-Policy:
  default-src 'self';
  script-src 'self' https://challenges.cloudflare.com https://cdn.example.com;
  frame-src https://challenges.cloudflare.com;
  connect-src 'self' https://challenges.cloudflare.com https://api.example.com;
  style-src 'self' 'unsafe-inline' https://challenges.cloudflare.com;
  img-src 'self' data: https:;
  font-src 'self' https://fonts.gstatic.com;

Next.js CSP (with nonce)

// next.config.js
const ContentSecurityPolicy = `
  default-src 'self';
  script-src 'self' 'nonce-${nonce}' https://challenges.cloudflare.com;
  frame-src https://challenges.cloudflare.com;
  connect-src 'self' https://challenges.cloudflare.com;
  style-src 'self' 'unsafe-inline';
`

Step 5: Implementation Guidance

Provide step-by-step implementation for user's platform:

Cloudflare Workers

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const response = await handleRequest(request, env)

    // Add Turnstile-compatible CSP
    response.headers.set('Content-Security-Policy',
      "default-src 'self'; " +
      "script-src 'self' https://challenges.cloudflare.com; " +
      "frame-src https://challenges.cloudflare.com; " +
      "connect-src 'self' https://challenges.cloudflare.com; " +
      "style-src 'unsafe-inline';"
    )

    return response
  }
}

Cloudflare Pages (_headers file)

/*
  Content-Security-Policy: default-src 'self'; script-src 'self' https://challenges.cloudflare.com; frame-src https://challenges.cloudflare.com; connect-src 'self' https://challenges.cloudflare.com; style-src 'unsafe-inline';

Nginx

server {
    add_header Content-Security-Policy "default-src 'self'; script-src 'self' https://challenges.cloudflare.com; frame-src https://challenges.cloudflare.com; connect-src 'self' https://challenges.cloudflare.com; style-src 'unsafe-inline';" always;
}

Apache (.htaccess)

Header set Content-Security-Policy "default-src 'self'; script-src 'self' https://challenges.cloudflare.com; frame-src https://challenges.cloudflare.com; connect-src 'self' https://challenges.cloudflare.com; style-src 'unsafe-inline';"

HTML Meta Tag (fallback)

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self' https://challenges.cloudflare.com; frame-src https://challenges.cloudflare.com; connect-src 'self' https://challenges.cloudflare.com; style-src 'unsafe-inline';">
  <!-- Must be in <head> before other scripts -->
</head>

⚠️ Important: Meta tag CSP must be placed before any <script> tags in <head>.

Common CSP Patterns

Pattern 1: Strict CSP with Nonce

Content-Security-Policy:
  script-src 'nonce-{random}' https://challenges.cloudflare.com;
  frame-src https://challenges.cloudflare.com;

Implementation:

<script nonce="{random}" src="/app.js"></script>
<!-- Turnstile script loads without nonce (whitelisted by domain) -->
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js"></script>

Pattern 2: CSP with Report-Only (testing)

Content-Security-Policy-Report-Only:
  script-src 'self' https://challenges.cloudflare.com;
  report-uri /csp-report;

Use Report-Only mode to test CSP without blocking resources.

Pattern 3: Multiple CSP Headers (merge)

Content-Security-Policy: default-src 'self';
Content-Security-Policy: script-src 'self' https://challenges.cloudflare.com;

⚠️ Warning: Multiple CSP headers combine with AND logic. Ensure compatibility.

Validation Checklist

After implementing CSP fixes, verify:

• ./scripts/check-csp.sh https://domain.com passes all checks
• Browser console shows no CSP violation errors
• Turnstile widget loads and renders
• Widget iframe is visible in DOM
• Challenge completes successfully
• Siteverify validation succeeds

Troubleshooting CSP Issues

Issue: Script still blocked after adding script-src

Cause: Multiple CSP headers combining restrictively Solution: Consolidate into single CSP header with all directives

Issue: Widget loads but styles broken

Cause: style-src too restrictive Solution: Add 'unsafe-inline' to style-src or whitelist https://challenges.cloudflare.com

Issue: CSP works locally but fails in production

Cause: Different CSP configuration in production environment Solution: Verify production server/CDN CSP settings match development

Issue: Meta tag CSP not working

Cause: HTTP header CSP overriding meta tag Solution: Remove meta tag and use HTTP header CSP instead (preferred)

Issue: Cloudflare Workers CSP not applying

Cause: Response headers set after response created Solution: Clone response and set headers on cloned response:

const response = await fetch(request)
const newResponse = new Response(response.body, response)
newResponse.headers.set('Content-Security-Policy', '...')
return newResponse

Advanced: CSP Reporting

Enable CSP reporting to monitor violations:

Content-Security-Policy:
  script-src 'self' https://challenges.cloudflare.com;
  frame-src https://challenges.cloudflare.com;
  report-uri /csp-report;
  report-to csp-endpoint;

Endpoint handler (Cloudflare Workers):

async function handleCSPReport(request: Request): Promise<Response> {
  const report = await request.json()
  console.error('CSP Violation:', report)

  // Log to analytics, monitoring, etc.

  return new Response('Report received', { status: 204 })
}

Security Considerations

Best Practices:

• ✅ Use default-src 'self' as baseline
• ✅ Whitelist only necessary domains
• ✅ Prefer HTTP header over meta tag
• ✅ Use nonces for inline scripts (when possible)
• ✅ Test with Report-Only mode first
• ✅ Monitor CSP violation reports

Avoid:

• ❌ 'unsafe-eval' (security risk)
• ❌ 'unsafe-inline' for scripts (use for styles only)
• ❌ Overly permissive wildcards (https://*)
• ❌ Mixing HTTP header and meta tag CSP
• ❌ Copying CSP without understanding directives

Reference Resources

CSP Validator: https://csp-evaluator.withgoogle.com/ MDN CSP Guide: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP check-csp.sh script: ./scripts/check-csp.sh <url> Error Codes Reference: references/error-codes.md (Error 200500)

Success Criteria

CSP debugging complete when:

• ✅ check-csp.sh script passes all validations
• ✅ No CSP violation errors in browser console
• ✅ Turnstile widget loads and functions correctly
• ✅ Challenge flow completes end-to-end
• ✅ CSP configuration documented for team

---

Agent Tools: Bash, Read, WebFetch Primary Script: check-csp.sh Related References: error-codes.md (Error 200500), widget-configs.md