memory-journal-mcp 8.0.1 → 9.1.0

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

@@ -1,236 +0,0 @@
-# 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

@@ -1,228 +0,0 @@
-# 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

@@ -1,102 +0,0 @@
-# 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)