references/turnstile/gotchas.md

# Troubleshooting & Gotchas

## Critical Rules

### ❌ Skipping Server-Side Validation
**Problem:** Client-only validation is easily bypassed.

**Solution:** Always validate on server.
```javascript
// CORRECT - Server validates token
app.post('/submit', async (req, res) => {
  const token = req.body['cf-turnstile-response'];
  const validation = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
    method: 'POST',
    body: JSON.stringify({ secret: SECRET, response: token })
  }).then(r => r.json());
  
  if (!validation.success) return res.status(403).json({ error: 'CAPTCHA failed' });
});
```

### ❌ Exposing Secret Key
**Problem:** Secret key leaked in client-side code.

**Solution:** Server-side validation only. Never send secret to client.

### ❌ Reusing Tokens (Single-Use Rule)
**Problem:** Tokens are single-use. Revalidation fails with `timeout-or-duplicate`.

**Solution:** Generate new token for each submission. Reset widget on error.
```javascript
if (!response.ok) window.turnstile.reset(widgetId);
```

### ❌ Not Handling Token Expiry
**Problem:** Tokens expire after 5 minutes.

**Solution:** Handle expiry callback or use auto-refresh.
```javascript
window.turnstile.render('#container', {
  sitekey: 'YOUR_SITE_KEY',
  'refresh-expired': 'auto', // or 'manual' with expired-callback
  'expired-callback': () => window.turnstile.reset(widgetId)
});
```

## Common Errors

| Error | Cause | Solution |
|-------|-------|----------|
| **Widget not rendering** | Incorrect sitekey, CSP blocking, file:// protocol | Check sitekey, add CSP for challenges.cloudflare.com, use http:// |
| **timeout-or-duplicate** | Token expired (>5min) or reused | Generate fresh token, don't cache >5min |
| **invalid-input-secret** | Wrong secret key | Verify secret from dashboard, check env vars |
| **missing-input-response** | Token not sent | Check form field name is 'cf-turnstile-response' |

## Framework Gotchas

### React: Widget Re-mounting
**Problem:** Widget re-renders on state change, losing token.

**Solution:** Control lifecycle with useRef.
```tsx
function TurnstileWidget({ onToken }) {
  const containerRef = useRef(null);
  const widgetIdRef = useRef(null);
  
  useEffect(() => {
    if (containerRef.current && !widgetIdRef.current) {
      widgetIdRef.current = window.turnstile.render(containerRef.current, {
        sitekey: 'YOUR_SITE_KEY',
        callback: onToken
      });
    }
    return () => {
      if (widgetIdRef.current) {
        window.turnstile.remove(widgetIdRef.current);
        widgetIdRef.current = null;
      }
    };
  }, []);
  
  return <div ref={containerRef} />;
}
```

### React StrictMode: Double Render
**Problem:** Widget renders twice in dev due to StrictMode.

**Solution:** Use cleanup function.
```tsx
useEffect(() => {
  const widgetId = window.turnstile.render('#container', { sitekey });
  return () => window.turnstile.remove(widgetId);
}, []);
```

### Next.js: SSR Hydration
**Problem:** `window.turnstile` undefined during SSR.

**Solution:** Use `'use client'` or dynamic import with `ssr: false`.
```tsx
'use client';
export default function Turnstile() { /* component */ }
```

### SPA: Navigation Without Cleanup
**Problem:** Navigating leaves orphaned widgets.

**Solution:** Remove widget in cleanup.
```javascript
// Vue
onBeforeUnmount(() => window.turnstile.remove(widgetId));

// React
useEffect(() => () => window.turnstile.remove(widgetId), []);
```

## Network & Security

### CSP Blocking
**Problem:** Content Security Policy blocks script/iframe.

**Solution:** Add CSP directives.
```html
<meta http-equiv="Content-Security-Policy" 
      content="script-src 'self' https://challenges.cloudflare.com; 
               frame-src https://challenges.cloudflare.com;">
```

### IP Address Forwarding
**Problem:** Server receives proxy IP instead of client IP.

**Solution:** Use correct header.
```javascript
// Cloudflare Workers
const ip = request.headers.get('CF-Connecting-IP');

// Behind proxy
const ip = request.headers.get('X-Forwarded-For')?.split(',')[0];
```

### CORS (Siteverify)
**Problem:** CORS error calling siteverify from browser.

**Solution:** Never call siteverify client-side. Call your backend, backend calls siteverify.

## Limits & Constraints

| Limit | Value | Impact |
|-------|-------|--------|
| Token validity | 5 minutes | Must regenerate after expiry |
| Token use | Single-use | Cannot revalidate same token |
| Widget size | 300x65px (normal), 130x120px (compact) | Plan layout |

## Debugging

### Console Logging
```javascript
window.turnstile.render('#container', {
  sitekey: 'YOUR_SITE_KEY',
  callback: (token) => console.log('✓ Token:', token),
  'error-callback': (code) => console.error('✗ Error:', code),
  'expired-callback': () => console.warn('⏱ Expired'),
  'timeout-callback': () => console.warn('⏱ Timeout')
});
```

### Check Token State
```javascript
const token = window.turnstile.getResponse(widgetId);
console.log('Token:', token || 'NOT READY');
console.log('Expired:', window.turnstile.isExpired(widgetId));
```

### Test Keys (Use First)
Always develop with test keys before production:
- Site: `1x00000000000000000000AA`
- Secret: `1x0000000000000000000000000000000AA`

### Network Tab
- Verify `api.js` loads (200 OK)
- Check siteverify request/response
- Look for 4xx/5xx errors

## Misconfigurations

### Wrong Key Pairing
**Problem:** Site key from one widget, secret from another.

**Solution:** Verify site key and secret are from same widget in dashboard.

### Test Keys in Production
**Problem:** Using test keys in production.

**Solution:** Environment-based keys.
```javascript
const SITE_KEY = process.env.NODE_ENV === 'production'
  ? process.env.TURNSTILE_SITE_KEY
  : '1x00000000000000000000AA';
```

### Missing Environment Variables
**Problem:** Secret undefined on server.

**Solution:** Check .env and verify loading.
```bash
# .env
TURNSTILE_SECRET=your_secret_here

# Verify
console.log('Secret loaded:', !!process.env.TURNSTILE_SECRET);
```

## Reference

- [Turnstile Docs](https://developers.cloudflare.com/turnstile/)
- [Dashboard](https://dash.cloudflare.com/?to=/:account/turnstile)
- [Error Codes](https://developers.cloudflare.com/turnstile/troubleshooting/)