memory-journal-mcp 7.7.1 → 8.0.0

package/skills/cloudflare/references/turn/gotchas.md

@@ -0,0 +1,236 @@
+# TURN Gotchas & Troubleshooting
+
+Common mistakes, security best practices, and troubleshooting for Cloudflare TURN.
+
+## Quick Reference
+
+| Issue                              | Solution                     | Details                                                        |
+| ---------------------------------- | ---------------------------- | -------------------------------------------------------------- |
+| Credentials not working            | Check TTL ≤ 48hrs            | [See Troubleshooting](#issue-turn-credentials-not-working)     |
+| Connection drops after ~48hrs      | Implement credential refresh | [See Connection Drops](#issue-connection-drops-after-48-hours) |
+| Port 53 fails in browser           | Filter server-side           | [See Port 53](#using-port-53-in-browsers)                      |
+| High packet loss                   | Check rate limits            | [See Rate Limits](#limits-per-turn-allocation)                 |
+| Connection fails after maintenance | Implement ICE restart        | [See ICE Restart](#ice-restart-required-scenarios)             |
+
+## Critical Constraints
+
+| Constraint                  | Value                      | Consequence if Violated                             |
+| --------------------------- | -------------------------- | --------------------------------------------------- |
+| Max credential TTL          | 48 hours (172800s)         | API rejects request                                 |
+| Credential revocation delay | ~seconds                   | Billing stops immediately, connection drops shortly |
+| IP allowlist update window  | 14 days (if IPs change)    | Connection fails if IPs change                      |
+| Packet rate                 | 5-10k pps per allocation   | Packet drops                                        |
+| Data rate                   | 50-100 Mbps per allocation | Packet drops                                        |
+| Unique IP rate              | >5 new IPs/sec             | Packet drops                                        |
+
+## Limits Per TURN Allocation
+
+**Per user** (not account-wide):
+
+- **IP addresses**: >5 new unique IPs per second
+- **Packet rate**: 5-10k packets per second (inbound/outbound)
+- **Data rate**: 50-100 Mbps (inbound/outbound)
+- **MTU**: No specific limit
+- **Burst rates**: Higher than documented
+
+Exceeding limits results in **packet drops**.
+
+## Common Mistakes
+
+### Setting TTL > 48 hours
+
+```typescript
+// ❌ BAD: API will reject
+const creds = await generate({ ttl: 604800 }) // 7 days
+
+// ✅ GOOD:
+const creds = await generate({ ttl: 86400 }) // 24 hours
+```
+
+### Hardcoding IPs without monitoring
+
+```typescript
+// ❌ BAD: IPs can change with 14-day notice
+const iceServers = [{ urls: 'turn:141.101.90.1:3478' }]
+
+// ✅ GOOD: Use DNS
+const iceServers = [{ urls: 'turn:turn.cloudflare.com:3478' }]
+```
+
+### Using port 53 in browsers
+
+```typescript
+// ❌ BAD: Blocked by Chrome/Firefox
+urls: ['turn:turn.cloudflare.com:53']
+
+// ✅ GOOD: Filter port 53
+urls: urls.filter((url) => !url.includes(':53'))
+```
+
+### Not handling credential expiry
+
+```typescript
+// ❌ BAD: Credentials expire but call continues → connection drops
+const creds = await fetchCreds()
+const pc = new RTCPeerConnection({ iceServers: creds })
+
+// ✅ GOOD: Refresh before expiry
+setInterval(() => refreshCredentials(pc), 3000000) // 50 min
+```
+
+### Missing ICE restart support
+
+```typescript
+// ❌ BAD: No recovery from TURN maintenance
+pc.addEventListener('iceconnectionstatechange', () => {
+  console.log('State changed:', pc.iceConnectionState)
+})
+
+// ✅ GOOD: Implement ICE restart
+pc.addEventListener('iceconnectionstatechange', async () => {
+  if (pc.iceConnectionState === 'failed') {
+    await refreshCredentials(pc)
+    pc.restartIce()
+  }
+})
+```
+
+### Exposing TURN key secret client-side
+
+```typescript
+// ❌ BAD: Secret exposed to client
+const secret = 'your-turn-key-secret'
+const response = await fetch(`https://rtc.live.cloudflare.com/v1/turn/...`, {
+  headers: { Authorization: `Bearer ${secret}` },
+})
+
+// ✅ GOOD: Generate credentials server-side
+const response = await fetch('/api/turn-credentials')
+```
+
+## ICE Restart Required Scenarios
+
+These events require ICE restart (see [patterns.md](./patterns.md#ice-restart-pattern)):
+
+1. **TURN server maintenance** (occasional on Cloudflare's network)
+2. **Network topology changes** (anycast routing changes)
+3. **Credential refresh** during long sessions (>1 hour)
+4. **Connection failure** (iceConnectionState === 'failed')
+
+Implement in all production apps:
+
+```typescript
+pc.addEventListener('iceconnectionstatechange', async () => {
+  if (pc.iceConnectionState === 'failed' || pc.iceConnectionState === 'disconnected') {
+    await refreshTURNCredentials(pc)
+    pc.restartIce()
+    const offer = await pc.createOffer({ iceRestart: true })
+    await pc.setLocalDescription(offer)
+    // Send offer to peer via signaling...
+  }
+})
+```
+
+Reference: [RFC 8445 Section 2.4](https://datatracker.ietf.org/doc/html/rfc8445#section-2.4)
+
+## Security Checklist
+
+- [ ] Credentials generated server-side only (never client-side)
+- [ ] TURN_KEY_SECRET in wrangler secrets, not vars
+- [ ] TTL ≤ expected session duration (and ≤ 48 hours)
+- [ ] Rate limiting on credential generation endpoint
+- [ ] Client authentication before issuing credentials
+- [ ] Credential revocation API for compromised sessions
+- [ ] No hardcoded IPs (or DNS monitoring in place)
+- [ ] Port 53 filtered for browser clients
+
+## Troubleshooting
+
+### Issue: TURN credentials not working
+
+**Check:**
+
+- Key ID and secret are correct
+- Credentials haven't expired (check TTL)
+- TTL doesn't exceed 172800 seconds (48 hours)
+- Server can reach rtc.live.cloudflare.com
+- Network allows outbound HTTPS
+
+**Solution:**
+
+```typescript
+// Validate before using
+if (ttl > 172800) {
+  throw new Error('TTL cannot exceed 48 hours')
+}
+```
+
+### Issue: Slow connection establishment
+
+**Solutions:**
+
+- Ensure proper ICE candidate gathering
+- Check network latency to Cloudflare edge
+- Verify firewall allows WebRTC ports (3478, 5349, 443)
+- Consider using TURN over TLS (port 443) for corporate networks
+
+### Issue: High packet loss
+
+**Check:**
+
+- Not exceeding rate limits (5-10k pps)
+- Not exceeding bandwidth limits (50-100 Mbps)
+- Not connecting to too many unique IPs (>5/sec)
+- Client network quality
+
+### Issue: Connection drops after ~48 hours
+
+**Cause**: Credentials expired (48hr max)
+
+**Solution**:
+
+- Set TTL to expected session duration
+- Implement credential refresh with setConfiguration()
+- Use ICE restart if connection fails
+
+```typescript
+// Refresh credentials before expiry
+const refreshInterval = ttl * 1000 - 60000 // 1 min early
+setInterval(async () => {
+  await refreshTURNCredentials(pc)
+}, refreshInterval)
+```
+
+### Issue: Port 53 URLs in browser fail silently
+
+**Cause**: Chrome/Firefox block port 53
+
+**Solution**: Filter port 53 URLs server-side:
+
+```typescript
+const filtered = urls.filter((url) => !url.includes(':53'))
+```
+
+### Issue: Hardcoded IPs stop working
+
+**Cause**: Cloudflare changed IP addresses (14-day notice)
+
+**Solution**:
+
+- Use DNS hostnames (`turn.cloudflare.com`)
+- Monitor DNS changes with automated alerts
+- Update allowlists within 14 days if using IP allowlisting
+
+## Cost Optimization
+
+1. Use appropriate TTLs (don't over-provision)
+2. Implement credential caching
+3. Set `iceTransportPolicy: 'all'` to try direct first (use `'relay'` only when necessary)
+4. Monitor bandwidth usage
+5. Free when used with Cloudflare Calls SFU
+
+## See Also
+
+- [api.md](./api.md) - Credential generation API, revocation
+- [configuration.md](./configuration.md) - IP allowlisting, monitoring
+- [patterns.md](./patterns.md) - ICE restart, credential refresh patterns

package/skills/cloudflare/references/turn/patterns.md

@@ -0,0 +1,228 @@
+# TURN Implementation Patterns
+
+Production-ready patterns for implementing Cloudflare TURN in WebRTC applications.
+
+## Prerequisites
+
+Before implementing these patterns, ensure you have:
+
+- TURN key created: see [api.md#create-turn-key](./api.md#create-turn-key)
+- Worker configured: see [configuration.md#cloudflare-worker-integration](./configuration.md#cloudflare-worker-integration)
+
+## Basic TURN Configuration (Browser)
+
+```typescript
+interface RTCIceServer {
+  urls: string | string[]
+  username?: string
+  credential?: string
+  credentialType?: 'password' | 'oauth'
+}
+
+async function getTURNConfig(): Promise<RTCIceServer[]> {
+  const response = await fetch('/api/turn-credentials')
+  const data = await response.json()
+
+  return [
+    {
+      urls: 'stun:stun.cloudflare.com:3478',
+    },
+    {
+      urls: [
+        'turn:turn.cloudflare.com:3478?transport=udp',
+        'turn:turn.cloudflare.com:3478?transport=tcp',
+        'turns:turn.cloudflare.com:5349?transport=tcp',
+        'turns:turn.cloudflare.com:443?transport=tcp',
+      ],
+      username: data.username,
+      credential: data.credential,
+      credentialType: 'password',
+    },
+  ]
+}
+
+// Use in RTCPeerConnection
+const iceServers = await getTURNConfig()
+const peerConnection = new RTCPeerConnection({ iceServers })
+```
+
+## Port Selection Strategy
+
+Recommended order for browser clients:
+
+1. **3478/udp** (primary, lowest latency)
+2. **3478/tcp** (fallback for UDP-blocked networks)
+3. **5349/tls** (corporate firewalls, most reliable)
+4. **443/tls** (alternate TLS port, firewall-friendly)
+
+**Avoid port 53**—blocked by Chrome and Firefox.
+
+```typescript
+function filterICEServersForBrowser(urls: string[]): string[] {
+  return urls
+    .filter((url) => !url.includes(':53')) // Remove port 53
+    .sort((a, b) => {
+      // Prioritize UDP over TCP over TLS
+      if (a.includes('transport=udp')) return -1
+      if (b.includes('transport=udp')) return 1
+      if (a.includes('transport=tcp') && !a.startsWith('turns:')) return -1
+      if (b.includes('transport=tcp') && !b.startsWith('turns:')) return 1
+      return 0
+    })
+}
+```
+
+## Credential Refresh (Mid-Session)
+
+When credentials expire during long calls:
+
+```typescript
+async function refreshTURNCredentials(pc: RTCPeerConnection): Promise<void> {
+  const newCreds = await fetch('/turn-credentials').then((r) => r.json())
+  const config = pc.getConfiguration()
+  config.iceServers = newCreds.iceServers
+  pc.setConfiguration(config)
+  // Note: setConfiguration() does NOT trigger ICE restart
+  // Combine with restartIce() if connection fails
+}
+
+// Auto-refresh before expiry
+setInterval(async () => {
+  await refreshTURNCredentials(peerConnection)
+}, 3000000) // 50 minutes if TTL is 1 hour
+```
+
+## ICE Restart Pattern
+
+After network change, TURN server maintenance, or credential expiry:
+
+```typescript
+pc.addEventListener('iceconnectionstatechange', async () => {
+  if (pc.iceConnectionState === 'failed') {
+    console.warn('ICE connection failed, restarting...')
+
+    // Refresh credentials
+    await refreshTURNCredentials(pc)
+
+    // Trigger ICE restart
+    pc.restartIce()
+    const offer = await pc.createOffer({ iceRestart: true })
+    await pc.setLocalDescription(offer)
+
+    // Send offer to peer via signaling channel...
+  }
+})
+```
+
+## Credentials Caching Pattern
+
+```typescript
+class TURNCredentialsManager {
+  private creds: {
+    username: string
+    credential: string
+    urls: string[]
+    expiresAt: number
+  } | null = null
+
+  async getCredentials(keyId: string, keySecret: string): Promise<RTCIceServer[]> {
+    const now = Date.now()
+
+    if (this.creds && this.creds.expiresAt > now) {
+      return this.buildIceServers(this.creds)
+    }
+
+    const ttl = 3600
+    if (ttl > 172800) throw new Error('TTL max 48hrs')
+
+    const res = await fetch(
+      `https://rtc.live.cloudflare.com/v1/turn/keys/${keyId}/credentials/generate`,
+      {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${keySecret}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ ttl }),
+      }
+    )
+
+    const data = await res.json()
+    const filteredUrls = data.iceServers.urls.filter((url: string) => !url.includes(':53'))
+
+    this.creds = {
+      username: data.iceServers.username,
+      credential: data.iceServers.credential,
+      urls: filteredUrls,
+      expiresAt: now + ttl * 1000 - 60000,
+    }
+
+    return this.buildIceServers(this.creds)
+  }
+
+  private buildIceServers(c: {
+    username: string
+    credential: string
+    urls: string[]
+  }): RTCIceServer[] {
+    return [
+      { urls: 'stun:stun.cloudflare.com:3478' },
+      {
+        urls: c.urls,
+        username: c.username,
+        credential: c.credential,
+        credentialType: 'password' as const,
+      },
+    ]
+  }
+}
+```
+
+## Common Use Cases
+
+```typescript
+// Video conferencing: TURN as fallback
+const config = { iceServers: await getTURNConfig(), iceTransportPolicy: 'all' }
+
+// IoT/predictable connectivity: force TURN
+const config = { iceServers: await getTURNConfig(), iceTransportPolicy: 'relay' }
+
+// Screen sharing: reduce overhead
+const pc = new RTCPeerConnection({ iceServers: await getTURNConfig(), bundlePolicy: 'max-bundle' })
+```
+
+## Integration with Cloudflare Calls SFU
+
+```typescript
+// TURN is automatically used when needed
+// Cloudflare Calls handles TURN + SFU coordination
+const session = await callsClient.createSession({
+  appId: 'your-app-id',
+  sessionId: 'meeting-123',
+})
+```
+
+## Debugging ICE Connectivity
+
+```typescript
+pc.addEventListener('icecandidate', (event) => {
+  if (event.candidate) {
+    console.log('ICE candidate:', event.candidate.type, event.candidate.protocol)
+  }
+})
+
+pc.addEventListener('iceconnectionstatechange', () => {
+  console.log('ICE state:', pc.iceConnectionState)
+})
+
+// Check selected candidate pair
+const stats = await pc.getStats()
+stats.forEach((report) => {
+  if (report.type === 'candidate-pair' && report.selected) {
+    console.log('Selected:', report)
+  }
+})
+```
+
+## See Also
+
+- [api.md](./api.md) - Credential generation API, types
+- [configuration.md](./configuration.md) - Worker setup, environment variables
+- [gotchas.md](./gotchas.md) - Common mistakes, troubleshooting

package/skills/cloudflare/references/turnstile/README.md

@@ -0,0 +1,102 @@
+# Cloudflare Turnstile Implementation Skill Reference
+
+Expert guidance for implementing Cloudflare Turnstile - a smart CAPTCHA alternative that protects websites from bots without showing traditional CAPTCHA puzzles.
+
+## Overview
+
+Turnstile is a user-friendly CAPTCHA alternative that runs challenges in the background without user interaction. It validates visitors automatically using signals like browser behavior, device fingerprinting, and machine learning.
+
+## Widget Types
+
+| Type                  | Interaction                        | Use Case                                |
+| --------------------- | ---------------------------------- | --------------------------------------- |
+| **Managed** (default) | Shows checkbox when needed         | Forms, logins - balance UX and security |
+| **Non-Interactive**   | Invisible, runs automatically      | Frictionless UX, low-risk actions       |
+| **Invisible**         | Hidden, triggered programmatically | Pre-clearance, API calls, headless      |
+
+## Quick Start
+
+### Implicit Rendering (HTML-based)
+
+```html
+<!-- 1. Add script -->
+<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
+
+<!-- 2. Add widget to form -->
+<form action="/submit" method="POST">
+  <div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY"></div>
+  <button type="submit">Submit</button>
+</form>
+```
+
+### Explicit Rendering (JavaScript-based)
+
+```html
+<div id="turnstile-container"></div>
+<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit"></script>
+<script>
+  window.turnstile.render('#turnstile-container', {
+    sitekey: 'YOUR_SITE_KEY',
+    callback: (token) => console.log('Token:', token),
+  })
+</script>
+```
+
+### Server Validation (Required)
+
+```javascript
+// Cloudflare Workers
+export default {
+  async fetch(request) {
+    const formData = await request.formData()
+    const token = formData.get('cf-turnstile-response')
+
+    const result = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        secret: env.TURNSTILE_SECRET,
+        response: token,
+        remoteip: request.headers.get('CF-Connecting-IP'),
+      }),
+    })
+
+    const validation = await result.json()
+    if (!validation.success) {
+      return new Response('Invalid CAPTCHA', { status: 400 })
+    }
+    // Process form...
+  },
+}
+```
+
+## Testing Keys
+
+**Critical for development/testing:**
+
+| Type                           | Key                                   | Behavior                           |
+| ------------------------------ | ------------------------------------- | ---------------------------------- |
+| **Site Key (Always Passes)**   | `1x00000000000000000000AA`            | Widget succeeds, token validates   |
+| **Site Key (Always Blocks)**   | `2x00000000000000000000AB`            | Widget fails visibly               |
+| **Site Key (Force Challenge)** | `3x00000000000000000000FF`            | Always shows interactive challenge |
+| **Secret Key (Testing)**       | `1x0000000000000000000000000000000AA` | Validates test tokens              |
+
+**Note:** Test keys work on `localhost` and any domain. Do NOT use in production.
+
+## Key Constraints
+
+- **Token expiry:** 5 minutes after generation
+- **Single-use:** Each token can only be validated once
+- **Server validation required:** Client-side checks are insufficient
+
+## Reading Order
+
+1. **[configuration.md](configuration.md)** - Setup, widget options, script loading
+2. **[api.md](api.md)** - JavaScript API, siteverify endpoints, TypeScript types
+3. **[patterns.md](patterns.md)** - Form integration, framework examples, validation patterns
+4. **[gotchas.md](gotchas.md)** - Common errors, debugging, limitations
+
+## See Also
+
+- [Cloudflare Turnstile Docs](https://developers.cloudflare.com/turnstile/)
+- [Dashboard](https://dash.cloudflare.com/?to=/:account/turnstile)