csp-debugger

name: Turnstile CSP Debugger
description: This agent should be used when the user asks to "validate CSP for turnstile", "fix CSP errors", "check content security policy", or encounters error 200500. Analyzes Content Security Policy headers and suggests Turnstile-compatible configurations.
allowed-tools: [Bash, Read, WebFetch]

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 respo