memory-journal-mcp 7.7.0 → 8.0.0

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

@@ -0,0 +1,52 @@
+# Cloudflare Spectrum Skill Reference
+
+## Overview
+
+Cloudflare Spectrum provides security and acceleration for ANY TCP or UDP-based application. It's a global Layer 4 (L4) reverse proxy running on Cloudflare's edge nodes that routes MQTT, email, file transfer, version control, games, and more through Cloudflare to mask origins and protect from DDoS attacks.
+
+**When to Use Spectrum**: When your protocol isn't HTTP/HTTPS (use Cloudflare proxy for HTTP). Spectrum handles everything else: SSH, gaming, databases, MQTT, SMTP, RDP, custom protocols.
+
+## Plan Capabilities
+
+| Capability            | Pro/Business        | Enterprise          |
+| --------------------- | ------------------- | ------------------- |
+| TCP protocols         | Selected ports only | All ports (1-65535) |
+| UDP protocols         | Selected ports only | All ports (1-65535) |
+| Port ranges           | ❌                  | ✅                  |
+| Argo Smart Routing    | ✅                  | ✅                  |
+| IP Firewall           | ✅                  | ✅                  |
+| Load balancer origins | ✅                  | ✅                  |
+
+## Decision Tree
+
+**What are you trying to do?**
+
+1. **Create/manage Spectrum app**
+   - Via Dashboard → See [Cloudflare Dashboard](https://dash.cloudflare.com)
+   - Via API → See [api.md](api.md) - REST endpoints
+   - Via SDK → See [api.md](api.md) - TypeScript/Python/Go examples
+   - Via IaC → See [configuration.md](configuration.md) - Terraform/Pulumi
+
+2. **Protect specific protocol**
+   - SSH → See [patterns.md](patterns.md#1-ssh-server-protection)
+   - Gaming (Minecraft, etc) → See [patterns.md](patterns.md#2-game-server)
+   - MQTT/IoT → See [patterns.md](patterns.md#3-mqtt-broker)
+   - SMTP/Email → See [patterns.md](patterns.md#4-smtp-relay)
+   - Database → See [patterns.md](patterns.md#5-database-proxy)
+   - RDP → See [patterns.md](patterns.md#6-rdp-remote-desktop)
+
+3. **Choose origin type**
+   - Direct IP (single server) → See [configuration.md](configuration.md#direct-ip-origin)
+   - CNAME (hostname) → See [configuration.md](configuration.md#cname-origin)
+   - Load balancer (HA/failover) → See [configuration.md](configuration.md#load-balancer-origin)
+
+## Reading Order
+
+1. Start with [patterns.md](patterns.md) for your specific protocol
+2. Then [configuration.md](configuration.md) for your origin type
+3. Check [gotchas.md](gotchas.md) before going to production
+4. Use [api.md](api.md) for programmatic access
+
+## See Also
+
+- [Cloudflare Docs](https://developers.cloudflare.com/spectrum/)

package/skills/cloudflare/references/spectrum/api.md

@@ -0,0 +1,184 @@
+## REST API Endpoints
+
+```
+GET    /zones/{zone_id}/spectrum/apps                    # List apps
+POST   /zones/{zone_id}/spectrum/apps                    # Create app
+GET    /zones/{zone_id}/spectrum/apps/{app_id}           # Get app
+PUT    /zones/{zone_id}/spectrum/apps/{app_id}           # Update app
+DELETE /zones/{zone_id}/spectrum/apps/{app_id}           # Delete app
+
+GET    /zones/{zone_id}/spectrum/analytics/aggregate/current
+GET    /zones/{zone_id}/spectrum/analytics/events/bytime
+GET    /zones/{zone_id}/spectrum/analytics/events/summary
+```
+
+## Request/Response Schemas
+
+### CreateSpectrumAppRequest
+
+```typescript
+interface CreateSpectrumAppRequest {
+  protocol: string // "tcp/22", "udp/53"
+  dns: {
+    type: 'CNAME' | 'ADDRESS'
+    name: string // "ssh.example.com"
+  }
+  origin_direct?: string[] // ["tcp://192.0.2.1:22"]
+  origin_dns?: { name: string } // {"name": "origin.example.com"}
+  origin_port?: number | { start: number; end: number }
+  proxy_protocol?: 'off' | 'v1' | 'v2' | 'simple'
+  ip_firewall?: boolean
+  tls?: 'off' | 'flexible' | 'full' | 'strict'
+  edge_ips?: {
+    type: 'dynamic' | 'static'
+    connectivity: 'all' | 'ipv4' | 'ipv6'
+  }
+  traffic_type?: 'direct' | 'http' | 'https'
+  argo_smart_routing?: boolean
+}
+```
+
+### SpectrumApp Response
+
+```typescript
+interface SpectrumApp {
+  id: string
+  protocol: string
+  dns: { type: string; name: string }
+  origin_direct?: string[]
+  origin_dns?: { name: string }
+  origin_port?: number | { start: number; end: number }
+  proxy_protocol: string
+  ip_firewall: boolean
+  tls: string
+  edge_ips: { type: string; connectivity: string; ips?: string[] }
+  argo_smart_routing: boolean
+  created_on: string
+  modified_on: string
+}
+```
+
+## TypeScript SDK
+
+```typescript
+import Cloudflare from 'cloudflare'
+
+const client = new Cloudflare({ apiToken: process.env.CLOUDFLARE_API_TOKEN })
+
+// Create
+const app = await client.spectrum.apps.create({
+  zone_id: 'your-zone-id',
+  protocol: 'tcp/22',
+  dns: { type: 'CNAME', name: 'ssh.example.com' },
+  origin_direct: ['tcp://192.0.2.1:22'],
+  ip_firewall: true,
+  tls: 'off',
+})
+
+// List
+const apps = await client.spectrum.apps.list({ zone_id: 'your-zone-id' })
+
+// Get
+const appDetails = await client.spectrum.apps.get({ zone_id: 'your-zone-id', app_id: app.id })
+
+// Update
+await client.spectrum.apps.update({ zone_id: 'your-zone-id', app_id: app.id, tls: 'full' })
+
+// Delete
+await client.spectrum.apps.delete({ zone_id: 'your-zone-id', app_id: app.id })
+
+// Analytics
+const analytics = await client.spectrum.analytics.aggregate({
+  zone_id: 'your-zone-id',
+  metrics: ['bytesIngress', 'bytesEgress'],
+  since: new Date(Date.now() - 3600000).toISOString(),
+})
+```
+
+## Python SDK
+
+```python
+from cloudflare import Cloudflare
+
+client = Cloudflare(api_token="your-api-token")
+
+# Create
+app = client.spectrum.apps.create(
+    zone_id="your-zone-id",
+    protocol="tcp/22",
+    dns={"type": "CNAME", "name": "ssh.example.com"},
+    origin_direct=["tcp://192.0.2.1:22"],
+    ip_firewall=True,
+    tls="off",
+)
+
+# List
+apps = client.spectrum.apps.list(zone_id="your-zone-id")
+
+# Get
+app_details = client.spectrum.apps.get(zone_id="your-zone-id", app_id=app.id)
+
+# Update
+client.spectrum.apps.update(zone_id="your-zone-id", app_id=app.id, tls="full")
+
+# Delete
+client.spectrum.apps.delete(zone_id="your-zone-id", app_id=app.id)
+
+# Analytics
+analytics = client.spectrum.analytics.aggregate(
+    zone_id="your-zone-id",
+    metrics=["bytesIngress", "bytesEgress"],
+    since=datetime.now() - timedelta(hours=1),
+)
+```
+
+## Go SDK
+
+```go
+import "github.com/cloudflare/cloudflare-go"
+
+api, _ := cloudflare.NewWithAPIToken("your-api-token")
+
+// Create
+app, _ := api.CreateSpectrumApplication(ctx, "zone-id", cloudflare.SpectrumApplication{
+    Protocol:         "tcp/22",
+    DNS:              cloudflare.SpectrumApplicationDNS{Type: "CNAME", Name: "ssh.example.com"},
+    OriginDirect:     []string{"tcp://192.0.2.1:22"},
+    IPFirewall:       true,
+    ArgoSmartRouting: true,
+})
+
+// List
+apps, _ := api.SpectrumApplications(ctx, "zone-id")
+
+// Delete
+_ = api.DeleteSpectrumApplication(ctx, "zone-id", app.ID)
+```
+
+## Analytics API
+
+**Metrics:**
+
+- `bytesIngress` - Bytes received from clients
+- `bytesEgress` - Bytes sent to clients
+- `count` - Number of connections
+- `duration` - Connection duration (seconds)
+
+**Dimensions:**
+
+- `event` - Connection event type
+- `appID` - Spectrum application ID
+- `coloName` - Datacenter name
+- `ipVersion` - IPv4 or IPv6
+
+**Example:**
+
+```bash
+curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/spectrum/analytics/aggregate/current?metrics=bytesIngress,bytesEgress,count&dimensions=appID" \
+  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
+```
+
+## See Also
+
+- [configuration.md](configuration.md) - Terraform/Pulumi
+- [patterns.md](patterns.md) - Protocol examples

package/skills/cloudflare/references/spectrum/configuration.md

@@ -0,0 +1,203 @@
+## Origin Types
+
+### Direct IP Origin
+
+Use when origin is a single server with static IP.
+
+**TypeScript SDK:**
+
+```typescript
+const app = await client.spectrum.apps.create({
+  zone_id: 'your-zone-id',
+  protocol: 'tcp/22',
+  dns: { type: 'CNAME', name: 'ssh.example.com' },
+  origin_direct: ['tcp://192.0.2.1:22'],
+  ip_firewall: true,
+  tls: 'off',
+})
+```
+
+**Terraform:**
+
+```hcl
+resource "cloudflare_spectrum_application" "ssh" {
+  zone_id  = var.zone_id
+  protocol = "tcp/22"
+
+  dns {
+    type = "CNAME"
+    name = "ssh.example.com"
+  }
+
+  origin_direct      = ["tcp://192.0.2.1:22"]
+  ip_firewall        = true
+  tls                = "off"
+  argo_smart_routing = true
+}
+```
+
+### CNAME Origin
+
+Use when origin is a hostname (not static IP). Spectrum resolves DNS dynamically.
+
+**TypeScript SDK:**
+
+```typescript
+const app = await client.spectrum.apps.create({
+  zone_id: 'your-zone-id',
+  protocol: 'tcp/3306',
+  dns: { type: 'CNAME', name: 'db.example.com' },
+  origin_dns: { name: 'db-primary.internal.example.com' },
+  origin_port: 3306,
+  tls: 'full',
+})
+```
+
+**Terraform:**
+
+```hcl
+resource "cloudflare_spectrum_application" "database" {
+  zone_id  = var.zone_id
+  protocol = "tcp/3306"
+
+  dns {
+    type = "CNAME"
+    name = "db.example.com"
+  }
+
+  origin_dns {
+    name = "db-primary.internal.example.com"
+  }
+
+  origin_port        = 3306
+  tls                = "full"
+  argo_smart_routing = true
+}
+```
+
+### Load Balancer Origin
+
+Use for high availability and failover.
+
+**Terraform:**
+
+```hcl
+resource "cloudflare_load_balancer" "game_lb" {
+  zone_id          = var.zone_id
+  name             = "game-lb.example.com"
+  default_pool_ids = [cloudflare_load_balancer_pool.game_pool.id]
+}
+
+resource "cloudflare_load_balancer_pool" "game_pool" {
+  name    = "game-primary"
+  origins { name = "game-1"; address = "192.0.2.1" }
+  monitor = cloudflare_load_balancer_monitor.tcp_monitor.id
+}
+
+resource "cloudflare_load_balancer_monitor" "tcp_monitor" {
+  type = "tcp"; port = 25565; interval = 60; timeout = 5
+}
+
+resource "cloudflare_spectrum_application" "game" {
+  zone_id  = var.zone_id
+  protocol = "tcp/25565"
+  dns { type = "CNAME"; name = "game.example.com" }
+  origin_dns { name = cloudflare_load_balancer.game_lb.name }
+  origin_port = 25565
+}
+```
+
+## TLS Configuration
+
+| Mode       | Description                    | Use Case                    | Origin Cert |
+| ---------- | ------------------------------ | --------------------------- | ----------- |
+| `off`      | No TLS                         | Non-encrypted (SSH, gaming) | No          |
+| `flexible` | TLS client→CF, plain CF→origin | Testing                     | No          |
+| `full`     | TLS end-to-end, self-signed OK | Production                  | Yes (any)   |
+| `strict`   | Full + valid cert verification | Max security                | Yes (CA)    |
+
+**Example:**
+
+```typescript
+const app = await client.spectrum.apps.create({
+  zone_id: 'your-zone-id',
+  protocol: 'tcp/3306',
+  dns: { type: 'CNAME', name: 'db.example.com' },
+  origin_direct: ['tcp://192.0.2.1:3306'],
+  tls: 'strict', // Validates origin certificate
+})
+```
+
+## Proxy Protocol
+
+Forwards real client IP to origin. Origin must support parsing.
+
+| Version  | Protocol | Use Case                       |
+| -------- | -------- | ------------------------------ |
+| `off`    | -        | Origin doesn't need client IP  |
+| `v1`     | TCP      | Most TCP apps (SSH, databases) |
+| `v2`     | TCP      | High-performance TCP           |
+| `simple` | UDP      | UDP applications               |
+
+**Compatibility:**
+
+- **v1**: HAProxy, nginx, SSH, most databases
+- **v2**: HAProxy 1.5+, nginx 1.11+
+- **simple**: Cloudflare-specific UDP format
+
+**Enable:**
+
+```typescript
+const app = await client.spectrum.apps.create({
+  // ...
+  proxy_protocol: 'v1', // Origin must parse PROXY header
+})
+```
+
+**Origin Config (nginx):**
+
+```nginx
+stream {
+    server {
+        listen 22 proxy_protocol;
+        proxy_pass backend:22;
+    }
+}
+```
+
+## IP Access Rules
+
+Enable `ip_firewall: true` then configure zone-level firewall rules.
+
+```typescript
+const app = await client.spectrum.apps.create({
+  // ...
+  ip_firewall: true, // Applies zone firewall rules
+})
+```
+
+## Port Ranges (Enterprise Only)
+
+```hcl
+resource "cloudflare_spectrum_application" "game_cluster" {
+  zone_id  = var.zone_id
+  protocol = "tcp/25565-25575"
+
+  dns {
+    type = "CNAME"
+    name = "games.example.com"
+  }
+
+  origin_direct = ["tcp://192.0.2.1"]
+
+  origin_port {
+    start = 25565
+    end   = 25575
+  }
+}
+```
+
+## See Also
+
+- [patterns.md](patterns.md) - Protocol-specific examples
+- [api.md](api.md) - REST/SDK reference

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

@@ -0,0 +1,155 @@
+## Common Issues
+
+### Connection Timeouts
+
+**Problem:** Connections fail or timeout  
+**Cause:** Origin firewall blocking Cloudflare IPs, origin service not running, incorrect DNS  
+**Solution:**
+
+1. Verify origin firewall allows Cloudflare IP ranges
+2. Check origin service running on correct port
+3. Ensure DNS record is CNAME (not A/AAAA)
+4. Verify origin IP/hostname is correct
+
+```bash
+# Test connectivity
+nc -zv app.example.com 22
+dig app.example.com
+```
+
+### Client IP Showing Cloudflare IP
+
+**Problem:** Origin logs show Cloudflare IPs not real client IPs  
+**Cause:** Proxy Protocol not enabled or origin not configured  
+**Solution:**
+
+```typescript
+// Enable in Spectrum app
+const app = await client.spectrum.apps.create({
+  // ...
+  proxy_protocol: 'v1', // TCP: v1/v2; UDP: simple
+})
+```
+
+**Origin config:**
+
+- **nginx**: `listen 22 proxy_protocol;`
+- **HAProxy**: `bind :22 accept-proxy`
+
+### TLS Errors
+
+**Problem:** TLS handshake failures, 525 errors  
+**Cause:** TLS mode mismatch
+
+| Error              | TLS Mode        | Problem            | Solution                        |
+| ------------------ | --------------- | ------------------ | ------------------------------- |
+| Connection refused | `full`/`strict` | Origin not TLS     | Use `tls: "off"` or enable TLS  |
+| 525 cert invalid   | `strict`        | Self-signed cert   | Use `tls: "full"` or valid cert |
+| Handshake timeout  | `flexible`      | Origin expects TLS | Use `tls: "full"`               |
+
+**Debug:**
+
+```bash
+openssl s_client -connect app.example.com:443 -showcerts
+```
+
+### SMTP Reverse DNS
+
+**Problem:** Email servers reject SMTP via Spectrum  
+**Cause:** Spectrum IPs lack PTR (reverse DNS) records  
+**Impact:** Many mail servers require valid rDNS for anti-spam
+
+**Solution:**
+
+- Outbound SMTP: NOT recommended through Spectrum
+- Inbound SMTP: Use Cloudflare Email Routing
+- Internal relay: Whitelist Spectrum IPs on destination
+
+### Proxy Protocol Compatibility
+
+**Problem:** Connection works but app behaves incorrectly  
+**Cause:** Origin doesn't support Proxy Protocol
+
+**Solution:**
+
+1. Verify origin supports version (v1: widely supported, v2: HAProxy 1.5+/nginx 1.11+)
+2. Test with `proxy_protocol: 'off'` first
+3. Configure origin to parse headers
+
+**nginx TCP:**
+
+```nginx
+stream {
+    server {
+        listen 22 proxy_protocol;
+        proxy_pass backend:22;
+    }
+}
+```
+
+**HAProxy:**
+
+```
+frontend ft_ssh
+    bind :22 accept-proxy
+```
+
+### Analytics Data Retention
+
+**Problem:** Historical data not available  
+**Cause:** Retention varies by plan
+
+| Plan       | Real-time | Historical |
+| ---------- | --------- | ---------- |
+| Pro        | Last hour | ❌         |
+| Business   | Last hour | Limited    |
+| Enterprise | Last hour | 90+ days   |
+
+**Solution:** Query within retention window or export to external system
+
+### Enterprise-Only Features
+
+**Problem:** Feature unavailable/errors  
+**Cause:** Requires Enterprise plan
+
+**Enterprise-only:**
+
+- Port ranges (`tcp/25565-25575`)
+- All TCP/UDP ports (Pro/Business: selected only)
+- Extended analytics retention
+- Advanced load balancing
+
+### IPv6 Considerations
+
+**Problem:** IPv6 clients can't connect or origin doesn't support IPv6  
+**Solution:** Configure `edge_ips.connectivity`
+
+```typescript
+const app = await client.spectrum.apps.create({
+  // ...
+  edge_ips: {
+    type: 'dynamic',
+    connectivity: 'ipv4', // Options: 'all', 'ipv4', 'ipv6'
+  },
+})
+```
+
+**Options:**
+
+- `all`: Dual-stack (default, requires origin support both)
+- `ipv4`: IPv4 only (use if origin lacks IPv6)
+- `ipv6`: IPv6 only (rare)
+
+## Limits
+
+| Resource    | Pro/Business | Enterprise  |
+| ----------- | ------------ | ----------- |
+| Max apps    | ~10-15       | 100+        |
+| Protocols   | Selected     | All TCP/UDP |
+| Port ranges | ❌           | ✅          |
+| Analytics   | ~1 hour      | 90+ days    |
+
+## See Also
+
+- [patterns.md](patterns.md) - Protocol examples
+- [configuration.md](configuration.md) - TLS/Proxy setup