@mohanscodex/spectra-code 0.4.8 → 0.5.0

package/skills/cloudflare-deploy/references/snippets/gotchas.md

@@ -0,0 +1,86 @@
+# Gotchas & Best Practices
+
+## Common Errors
+
+### 1000: "Snippet execution failed"
+Runtime error or syntax error. Wrap code in try/catch:
+```javascript
+try { return await fetch(request); }
+catch (error) { return new Response(`Error: ${error.message}`, { status: 500 }); }
+```
+
+### 1100: "Exceeded execution limit"
+Code takes >5ms CPU. Simplify logic or move to Workers.
+
+### 1201: "Multiple origin fetches"
+Call `fetch(request)` exactly once:
+```javascript
+// ❌ Multiple origin fetches
+const r1 = await fetch(request); const r2 = await fetch(request);
+// ✅ Single fetch, reuse response
+const response = await fetch(request);
+```
+
+### 1202: "Subrequest limit exceeded"
+Pro: 2 subrequests, Business/Enterprise: 5. Reduce fetch calls.
+
+### "Cannot set property on immutable object"
+Clone before modifying:
+```javascript
+const modifiedRequest = new Request(request);
+modifiedRequest.headers.set("X-Custom", "value");
+```
+
+### "caches is not defined"
+Cache API NOT available in Snippets. Use Workers.
+
+### "Module not found"
+Snippets don't support `import`. Use inline code or Workers.
+
+## Best Practices
+
+### Performance
+- Keep code <10KB (32KB limit)
+- Optimize for 5ms CPU
+- Clone only when modifying
+- Minimize subrequests
+
+### Security
+- Validate all inputs
+- Use Web Crypto API for hashing
+- Sanitize headers before origin
+- Don't log secrets
+
+### Debugging
+```javascript
+newResponse.headers.set("X-Debug-Country", request.cf.country);
+```
+```bash
+curl -H "X-Test: true" https://example.com -v
+```
+
+## Available APIs
+
+**✅ Available:** `fetch()`, `Request`, `Response`, `Headers`, `URL`, `crypto.subtle`, `crypto.randomUUID()`, `atob()`/`btoa()`, `JSON`
+
+**❌ NOT Available:** `caches`, `KV`, `D1`, `R2`, `Durable Objects`, `WebSocket`, `HTMLRewriter`, `import`, Node.js APIs
+
+## Limits
+
+| Resource | Limit |
+|----------|-------|
+| Snippet size | 32KB |
+| Execution time | 5ms CPU |
+| Subrequests (Pro/Biz) | 2/5 |
+| Snippets/zone | 20 |
+
+## Performance Benchmarks
+
+| Operation | Time |
+|-----------|------|
+| Header set | <0.1ms |
+| URL parsing | <0.2ms |
+| fetch() | 1-3ms |
+| SHA-256 | 0.5-1ms |
+
+**Migrate to Workers when:** >5ms needed, >5 subrequests, need storage (KV/D1/R2), need npm packages, >32KB code

package/skills/cloudflare-deploy/references/snippets/patterns.md

@@ -0,0 +1,135 @@
+# Snippets Patterns
+
+## Security Headers
+
+```javascript
+export default {
+  async fetch(request) {
+    const response = await fetch(request);
+    const newResponse = new Response(response.body, response);
+    newResponse.headers.set("X-Frame-Options", "DENY");
+    newResponse.headers.set("X-Content-Type-Options", "nosniff");
+    newResponse.headers.delete("X-Powered-By");
+    return newResponse;
+  }
+}
+```
+
+**Rule:** `true` (all requests)
+
+## Geo-Based Routing
+
+```javascript
+export default {
+  async fetch(request) {
+    const country = request.cf.country;
+    if (["GB", "DE", "FR"].includes(country)) {
+      const url = new URL(request.url);
+      url.hostname = url.hostname.replace(".com", ".eu");
+      return Response.redirect(url.toString(), 302);
+    }
+    return fetch(request);
+  }
+}
+```
+
+## A/B Testing
+
+```javascript
+export default {
+  async fetch(request) {
+    const cookies = request.headers.get("Cookie") || "";
+    let variant = cookies.match(/ab_test=([AB])/)?.[1] || (Math.random() < 0.5 ? "A" : "B");
+    
+    const req = new Request(request);
+    req.headers.set("X-Variant", variant);
+    const response = await fetch(req);
+    
+    if (!cookies.includes("ab_test=")) {
+      const newResponse = new Response(response.body, response);
+      newResponse.headers.append("Set-Cookie", `ab_test=${variant}; Path=/; Secure`);
+      return newResponse;
+    }
+    return response;
+  }
+}
+```
+
+## Bot Detection
+
+```javascript
+export default {
+  async fetch(request) {
+    const botScore = request.cf.botManagement?.score;
+    if (botScore && botScore < 30) return new Response("Denied", { status: 403 });
+    return fetch(request);
+  }
+}
+```
+
+**Requires:** Bot Management plan
+
+## API Auth Header Injection
+
+```javascript
+export default {
+  async fetch(request) {
+    if (new URL(request.url).pathname.startsWith("/api/")) {
+      const req = new Request(request);
+      req.headers.set("X-Internal-Auth", "secret_token");
+      req.headers.delete("Authorization");
+      return fetch(req);
+    }
+    return fetch(request);
+  }
+}
+```
+
+## CORS Headers
+
+```javascript
+export default {
+  async fetch(request) {
+    if (request.method === "OPTIONS") {
+      return new Response(null, {
+        status: 204,
+        headers: {
+          "Access-Control-Allow-Origin": "*",
+          "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE",
+          "Access-Control-Allow-Headers": "Content-Type, Authorization"
+        }
+      });
+    }
+    const response = await fetch(request);
+    const newResponse = new Response(response.body, response);
+    newResponse.headers.set("Access-Control-Allow-Origin", "*");
+    return newResponse;
+  }
+}
+```
+
+## Maintenance Mode
+
+```javascript
+export default {
+  async fetch(request) {
+    if (request.headers.get("X-Bypass-Token") === "admin") return fetch(request);
+    return new Response("<h1>Maintenance</h1>", {
+      status: 503,
+      headers: { "Content-Type": "text/html", "Retry-After": "3600" }
+    });
+  }
+}
+```
+
+## Pattern Selection
+
+| Pattern | Complexity | Use Case |
+|---------|-----------|----------|
+| Security Headers | Low | All sites |
+| Geo-Routing | Low | Regional content |
+| A/B Testing | Medium | Experiments |
+| Bot Detection | Medium | Requires Bot Management |
+| API Auth | Low | Backend protection |
+| CORS | Low | API endpoints |
+| Maintenance | Low | Deployments |

package/skills/cloudflare-deploy/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-deploy/references/spectrum/api.md

@@ -0,0 +1,181 @@
+## 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-deploy/references/spectrum/configuration.md

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