@mohanscodex/spectra-code 0.4.9 → 0.5.0

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

@@ -0,0 +1,204 @@
+# Gotchas & Troubleshooting
+
+## Execution Order
+
+**Problem:** Rules execute in unexpected order
+**Cause:** Misunderstanding phase execution
+**Solution:**
+
+Phases execute sequentially (can't be changed):
+1. `http_request_firewall_custom` - Custom rules
+2. `http_request_firewall_managed` - Managed rulesets
+3. `http_ratelimit` - Rate limiting
+
+Within phase: top-to-bottom, first match wins (unless `skip`)
+
+```typescript
+// WRONG: Can't mix phase-specific actions
+await client.rulesets.create({
+  phase: 'http_request_firewall_custom',
+  rules: [
+    { action: 'block', expression: 'cf.waf.score gt 50' },
+    { action: 'execute', action_parameters: { id: 'managed_id' } }, // WRONG
+  ],
+});
+
+// CORRECT: Separate rulesets per phase
+await client.rulesets.create({ phase: 'http_request_firewall_custom', rules: [...] });
+await client.rulesets.create({ phase: 'http_request_firewall_managed', rules: [...] });
+```
+
+## Expression Errors
+
+**Problem:** Syntax errors prevent deployment
+**Cause:** Invalid field/operator/syntax
+**Solution:**
+
+```typescript
+// Common mistakes
+'http.request.path' → 'http.request.uri.path' // Correct field
+'ip.geoip.country eq US' → 'ip.geoip.country eq "US"' // Quote strings
+'http.user_agent eq "Mozilla"' → 'lower(http.user_agent) contains "mozilla"' // Case sensitivity
+'matches ".*[.jpg"' → 'matches ".*\\.jpg$"' // Valid regex
+```
+
+Test expressions in Security Events before deploying.
+
+## Skip Rule Pitfalls
+
+**Problem:** Skip rules don't work as expected
+**Cause:** Misunderstanding skip scope
+**Solution:**
+
+Skip types:
+- `ruleset: 'current'` - Skip remaining rules in current ruleset only
+- `phases: ['phase_name']` - Skip entire phases
+
+```typescript
+// WRONG: Trying to skip managed rules from custom phase
+// In http_request_firewall_custom:
+{
+  action: 'skip',
+  action_parameters: { ruleset: 'current' },
+  expression: 'ip.src in {192.0.2.0/24}',
+}
+// This only skips remaining custom rules, not managed rules
+
+// CORRECT: Skip specific phases
+{
+  action: 'skip',
+  action_parameters: {
+    phases: ['http_request_firewall_managed', 'http_ratelimit'],
+  },
+  expression: 'ip.src in {192.0.2.0/24}',
+}
+```
+
+## Update Replaces All Rules
+
+**Problem:** Updating ruleset deletes other rules
+**Cause:** `update()` replaces entire rule list
+**Solution:**
+
+```typescript
+// WRONG: This deletes all existing rules!
+await client.rulesets.update({
+  zone_id: 'zone_id',
+  ruleset_id: 'ruleset_id',
+  rules: [{ action: 'block', expression: 'cf.waf.score gt 50' }],
+});
+
+// CORRECT: Get existing rules first
+const ruleset = await client.rulesets.get({ zone_id: 'zone_id', ruleset_id: 'ruleset_id' });
+await client.rulesets.update({
+  zone_id: 'zone_id',
+  ruleset_id: 'ruleset_id',
+  rules: [...ruleset.rules, { action: 'block', expression: 'cf.waf.score gt 50' }],
+});
+```
+
+## Override Conflicts
+
+**Problem:** Managed ruleset overrides don't apply
+**Cause:** Rule ID doesn't exist or category name incorrect
+**Solution:**
+
+```typescript
+// List managed ruleset rules to find IDs
+const ruleset = await client.rulesets.get({
+  zone_id: 'zone_id',
+  ruleset_id: 'efb7b8c949ac4650a09736fc376e9aee',
+});
+console.log(ruleset.rules.map(r => ({ id: r.id, description: r.description })));
+
+// Use correct IDs in overrides
+{ action: 'execute', action_parameters: { id: 'efb7b8c949ac4650a09736fc376e9aee', 
+  overrides: { rules: [{ id: '5de7edfa648c4d6891dc3e7f84534ffa', action: 'log' }] } } }
+```
+
+## False Positives
+
+**Problem:** Legitimate traffic blocked
+**Cause:** Aggressive rules/thresholds
+**Solution:**
+
+1. Start with log mode: `overrides: { action: 'log' }`
+2. Review Security Events to identify false positives
+3. Override specific rules: `overrides: { rules: [{ id: 'rule_id', action: 'log' }] }`
+
+## Rate Limiting NAT Issues
+
+**Problem:** Users behind NAT hit rate limits too quickly
+**Cause:** Multiple users sharing single IP
+**Solution:**
+
+Add more characteristics: User-Agent, session cookie, or authorization header
+```typescript
+{
+  action: 'block',
+  expression: 'http.request.uri.path starts_with "/api"',
+  action_parameters: {
+    ratelimit: {
+      characteristics: ['cf.colo.id', 'ip.src', 'http.request.cookies["session"][0]'],
+      period: 60,
+      requests_per_period: 100,
+    },
+  },
+}
+```
+
+## Performance Issues
+
+**Problem:** Increased latency
+**Cause:** Complex expressions, excessive rules
+**Solution:**
+
+1. Skip static assets early: `action: 'skip'` for `\\.(jpg|css|js)$`
+2. Path-based deployment: Only run managed on `/api` or `/admin`
+3. Disable unused categories: `{ category: 'wordpress', enabled: false }`
+4. Prefer string operators over regex: `starts_with` vs `matches`
+
+## Limits & Quotas
+
+| Resource | Free | Pro | Business | Enterprise |
+|----------|------|-----|----------|------------|
+| Custom rules | 5 | 20 | 100 | 1000 |
+| Rate limiting rules | 1 | 10 | 25 | 100 |
+| Rule expression length | 4096 chars | 4096 chars | 4096 chars | 4096 chars |
+| Rules per ruleset | 75 | 75 | 400 | 1000 |
+| Managed rulesets | Yes | Yes | Yes | Yes |
+| Rate limit characteristics | 2 | 3 | 5 | 5 |
+
+**Important Notes:**
+- Rules execute in order; first match wins (except skip rules)
+- Expression evaluation stops at first `false` in AND chains
+- `matches` regex operator is slower than string operators
+- Rate limit counting happens before mitigation
+
+## API Errors
+
+**Problem:** API calls fail with cryptic errors
+**Cause:** Invalid parameters or permissions
+**Solution:**
+
+```typescript
+// Error: "Invalid phase" → Use exact phase name
+phase: 'http_request_firewall_custom'
+
+// Error: "Ruleset already exists" → Use update() or list first
+const rulesets = await client.rulesets.list({ zone_id, phase: 'http_request_firewall_custom' });
+if (rulesets.result.length > 0) {
+  await client.rulesets.update({ zone_id, ruleset_id: rulesets.result[0].id, rules: [...] });
+}
+
+// Error: "Action not supported" → Check phase/action compatibility
+// 'execute' only in http_request_firewall_managed
+// Rate limit config only in http_ratelimit phase
+
+// Error: "Expression parse error" → Common fixes:
+'ip.geoip.country eq "US"'   // Quote strings
+'cf.waf.score gt 40'         // Use 'gt' not '>'
+'http.request.uri.path'      // Not 'http.request.path'
+```
+
+**Tip**: Test expressions in dashboard Security Events before deploying.

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

@@ -0,0 +1,197 @@
+# Common Patterns
+
+## Deploy Managed Rulesets
+
+```typescript
+// Deploy Cloudflare Managed Ruleset (default)
+await client.rulesets.create({
+  zone_id: 'zone_id',
+  kind: 'zone',
+  phase: 'http_request_firewall_managed',
+  name: 'Cloudflare Managed Ruleset',
+  rules: [{
+    action: 'execute',
+    action_parameters: {
+      id: 'efb7b8c949ac4650a09736fc376e9aee', // Cloudflare Managed
+      // Or: '4814384a9e5d4991b9815dcfc25d2f1f' for OWASP CRS
+      // Or: 'c2e184081120413c86c3ab7e14069605' for Exposed Credentials
+    },
+    expression: 'true', // All requests
+    // Or: 'http.request.uri.path starts_with "/api"' for specific paths
+    enabled: true,
+  }],
+});
+```
+
+## Override Managed Ruleset
+
+```typescript
+await client.rulesets.create({
+  zone_id: 'zone_id',
+  phase: 'http_request_firewall_managed',
+  rules: [{
+    action: 'execute',
+    action_parameters: {
+      id: 'efb7b8c949ac4650a09736fc376e9aee',
+      overrides: {
+        // Override specific rules
+        rules: [
+          { id: '5de7edfa648c4d6891dc3e7f84534ffa', action: 'log' },
+          { id: '75a0060762034b9dad4e883afc121b4c', enabled: false },
+        ],
+        // Override categories: wordpress, sqli, xss, rce, etc.
+        categories: [
+          { category: 'wordpress', enabled: false },
+          { category: 'sqli', action: 'log' },
+        ],
+      },
+    },
+    expression: 'true',
+  }],
+});
+```
+
+## Custom Rules
+
+```typescript
+await client.rulesets.create({
+  zone_id: 'zone_id',
+  kind: 'zone',
+  phase: 'http_request_firewall_custom',
+  name: 'Custom WAF Rules',
+  rules: [
+    // Attack score-based
+    { action: 'block', expression: 'cf.waf.score gt 50', enabled: true },
+    { action: 'challenge', expression: 'cf.waf.score gt 20', enabled: true },
+    
+    // Specific attack types
+    { action: 'block', expression: 'cf.waf.score.sqli gt 30 or cf.waf.score.xss gt 30', enabled: true },
+    
+    // Geographic blocking
+    { action: 'block', expression: 'ip.geoip.country in {"CN" "RU"}', enabled: true },
+  ],
+});
+```
+
+## Rate Limiting
+
+```typescript
+await client.rulesets.create({
+  zone_id: 'zone_id',
+  kind: 'zone',
+  phase: 'http_ratelimit',
+  name: 'Rate Limits',
+  rules: [
+    // Per-IP global limit
+    {
+      action: 'block',
+      expression: 'true',
+      action_parameters: {
+        ratelimit: {
+          characteristics: ['cf.colo.id', 'ip.src'],
+          period: 60,
+          requests_per_period: 100,
+          mitigation_timeout: 600,
+        },
+      },
+    },
+    
+    // Login endpoint (stricter)
+    {
+      action: 'block',
+      expression: 'http.request.uri.path eq "/api/login"',
+      action_parameters: {
+        ratelimit: {
+          characteristics: ['ip.src'],
+          period: 60,
+          requests_per_period: 5,
+          mitigation_timeout: 600,
+        },
+      },
+    },
+    
+    // API writes only (using counting_expression)
+    {
+      action: 'block',
+      expression: 'http.request.uri.path starts_with "/api"',
+      action_parameters: {
+        ratelimit: {
+          characteristics: ['cf.colo.id', 'ip.src'],
+          period: 60,
+          requests_per_period: 50,
+          counting_expression: 'http.request.method ne "GET"',
+        },
+      },
+    },
+  ],
+});
+```
+
+## Skip Rules
+
+```typescript
+await client.rulesets.create({
+  zone_id: 'zone_id',
+  kind: 'zone',
+  phase: 'http_request_firewall_custom',
+  name: 'Skip Rules',
+  rules: [
+    // Skip static assets (current ruleset only)
+    {
+      action: 'skip',
+      action_parameters: { ruleset: 'current' },
+      expression: 'http.request.uri.path matches "\\.(jpg|css|js|woff2?)$"',
+    },
+    
+    // Skip all WAF phases for trusted IPs
+    {
+      action: 'skip',
+      action_parameters: {
+        phases: ['http_request_firewall_managed', 'http_ratelimit'],
+      },
+      expression: 'ip.src in {192.0.2.0/24}',
+    },
+  ],
+});
+```
+
+## Complete Setup Example
+
+Combine all three phases for comprehensive protection:
+
+```typescript
+const client = new Cloudflare({ apiToken: process.env.CF_API_TOKEN });
+const zoneId = process.env.ZONE_ID;
+
+// 1. Custom rules (execute first)
+await client.rulesets.create({
+  zone_id: zoneId,
+  phase: 'http_request_firewall_custom',
+  rules: [
+    { action: 'skip', action_parameters: { phases: ['http_request_firewall_managed', 'http_ratelimit'] }, expression: 'ip.src in {192.0.2.0/24}' },
+    { action: 'block', expression: 'cf.waf.score gt 50' },
+    { action: 'managed_challenge', expression: 'cf.waf.score gt 20' },
+  ],
+});
+
+// 2. Managed ruleset (execute second)
+await client.rulesets.create({
+  zone_id: zoneId,
+  phase: 'http_request_firewall_managed',
+  rules: [{
+    action: 'execute',
+    action_parameters: { id: 'efb7b8c949ac4650a09736fc376e9aee', overrides: { categories: [{ category: 'wordpress', enabled: false }] } },
+    expression: 'true',
+  }],
+});
+
+// 3. Rate limiting (execute third)
+await client.rulesets.create({
+  zone_id: zoneId,
+  phase: 'http_ratelimit',
+  rules: [
+    { action: 'block', expression: 'true', action_parameters: { ratelimit: { characteristics: ['cf.colo.id', 'ip.src'], period: 60, requests_per_period: 100, mitigation_timeout: 600 } } },
+    { action: 'block', expression: 'http.request.uri.path eq "/api/login"', action_parameters: { ratelimit: { characteristics: ['ip.src'], period: 60, requests_per_period: 5, mitigation_timeout: 600 } } },
+  ],
+});
+```

package/skills/cloudflare-deploy/references/web-analytics/README.md

@@ -0,0 +1,140 @@
+# Cloudflare Web Analytics
+
+Privacy-first web analytics providing Core Web Vitals, traffic metrics, and user insights without compromising visitor privacy.
+
+## Overview
+
+Cloudflare Web Analytics provides:
+- **Core Web Vitals** - LCP, FID, CLS, INP, TTFB monitoring
+- **Page views & visits** - Traffic patterns without cookies
+- **Referrers & paths** - Traffic sources and popular pages
+- **Device & browser data** - User agent breakdown
+- **Geographic data** - Country-level visitor distribution
+- **Privacy-first** - No cookies, fingerprinting, or PII collection
+- **Free** - No cost, unlimited pageviews
+
+**Important:** Web Analytics is **dashboard-only**. No API exists for programmatic data access.
+
+## Quick Start Decision Tree
+
+```
+Is your site proxied through Cloudflare?
+├─ YES → Use automatic injection (configuration.md)
+│   ├─ Enable auto-injection in dashboard
+│   └─ No code changes needed (unless Cache-Control: no-transform)
+│
+└─ NO → Use manual beacon integration (integration.md)
+    ├─ Add JS snippet to HTML
+    ├─ Use spa: true for React/Vue/Next.js
+    └─ Configure CSP if needed
+```
+
+## Reading Order
+
+1. **[configuration.md](configuration.md)** - Setup for proxied vs non-proxied sites
+2. **[integration.md](integration.md)** - Framework-specific beacon integration (React, Next.js, Vue, Nuxt, etc.)
+3. **[patterns.md](patterns.md)** - Common use cases (performance monitoring, GDPR consent, multi-site tracking)
+4. **[gotchas.md](gotchas.md)** - Troubleshooting (SPA tracking, CSP issues, hash routing limitations)
+
+## When to Use Each File
+
+- **Setting up for first time?** → Start with configuration.md
+- **Using React/Next.js/Vue/Nuxt?** → Go to integration.md for framework code
+- **Need GDPR consent loading?** → See patterns.md
+- **Beacon not loading or no data?** → Check gotchas.md
+- **SPA not tracking navigation?** → See integration.md for `spa: true` config
+
+## Key Concepts
+
+### Proxied vs Non-Proxied Sites
+
+| Type | Description | Beacon Injection | Limit |
+|------|-------------|------------------|-------|
+| **Proxied** | DNS through Cloudflare (orange cloud) | Automatic or manual | Unlimited |
+| **Non-proxied** | External hosting, manual beacon | Manual only | 10 sites max |
+
+### SPA Mode
+
+**Critical for modern frameworks:**
+```json
+{"token": "YOUR_TOKEN", "spa": true}
+```
+
+Without `spa: true`, client-side navigation (React Router, Vue Router, Next.js routing) will NOT be tracked. Only initial page loads will register.
+
+### CSP Requirements
+
+If using Content Security Policy, allow both domains:
+```
+script-src https://static.cloudflareinsights.com https://cloudflareinsights.com;
+```
+
+## Features
+
+### Core Web Vitals Debugging
+- **LCP (Largest Contentful Paint)** - Identifies slow-loading hero images/elements
+- **FID (First Input Delay)** - Interaction responsiveness (legacy metric)
+- **INP (Interaction to Next Paint)** - Modern interaction responsiveness metric
+- **CLS (Cumulative Layout Shift)** - Visual stability issues
+- **TTFB (Time to First Byte)** - Server response performance
+
+Dashboard shows top 5 problematic elements with CSS selectors for debugging.
+
+### Traffic Filters
+- **Bot filtering** - Exclude automated traffic from metrics
+- **Date ranges** - Custom time period analysis
+- **Geographic** - Country-level filtering
+- **Device type** - Desktop, mobile, tablet breakdown
+- **Browser/OS** - User agent filtering
+
+### Rules (Advanced - Plan-dependent)
+
+Create custom tracking rules for advanced configurations:
+
+**Sample Rate Rules:**
+- Reduce data collection percentage for high-traffic sites
+- Example: Track only 50% of visitors to reduce volume
+
+**Path-Based Rules:**
+- Different behavior per route
+- Example: Exclude `/admin/*` or `/internal/*` from tracking
+
+**Host-Based Rules:**
+- Multi-domain configurations
+- Example: Separate tracking for staging vs production subdomains
+
+**Availability:** Rules feature depends on your Cloudflare plan. Check dashboard under Web Analytics → Rules to see if available. Free plans may have limited or no access.
+
+## Plan Limits
+
+| Feature | Free | Notes |
+|---------|------|-------|
+| Proxied sites | Unlimited | DNS through Cloudflare |
+| Non-proxied sites | 10 | External hosting |
+| Pageviews | Unlimited | No volume limits |
+| Data retention | 6 months | Rolling window |
+| Rules | Plan-dependent | Check dashboard |
+
+## Privacy & Compliance
+
+- **No cookies** - Zero client-side storage
+- **No fingerprinting** - No tracking across sites
+- **No PII** - IP addresses not stored
+- **GDPR-friendly** - Minimal data collection
+- **CCPA-compliant** - No personal data sale
+
+**EU opt-out:** Dashboard option to exclude EU visitor data entirely.
+
+## Limitations
+
+- **Dashboard-only** - No API for programmatic access
+- **No real-time** - 5-10 minute data delay
+- **No custom events** - Automatic pageview/navigation tracking only
+- **History API only** - Hash-based routing (`#/path`) not supported
+- **No session replay** - Metrics only, no user recordings
+- **No form tracking** - Page navigation tracking only
+
+## See Also
+
+- [Cloudflare Web Analytics Docs](https://developers.cloudflare.com/analytics/web-analytics/)
+- [Core Web Vitals Guide](https://web.dev/vitals/)

package/skills/cloudflare-deploy/references/web-analytics/configuration.md

@@ -0,0 +1,76 @@
+# Configuration
+
+## Setup Methods
+
+### Proxied Sites (Automatic)
+
+Dashboard → Web Analytics → Add site → Select hostname → Done
+
+| Injection Option | Description |
+|------------------|-------------|
+| Enable | Auto-inject for all visitors (default) |
+| Enable, excluding EU | No injection for EU (GDPR) |
+| Enable with manual snippet | You add beacon manually |
+| Disable | Pause tracking |
+
+**Fails if response has:** `Cache-Control: public, no-transform`
+
+**CSP required:**
+```
+script-src https://static.cloudflareinsights.com https://cloudflareinsights.com;
+```
+
+### Non-Proxied Sites (Manual)
+
+Dashboard → Web Analytics → Add site → Enter hostname → Copy snippet
+
+```html
+<script defer src='https://static.cloudflareinsights.com/beacon.min.js' 
+        data-cf-beacon='{"token": "YOUR_TOKEN", "spa": true}'></script>
+```
+
+**Limits:** 10 non-proxied sites per account
+
+## SPA Mode
+
+**Enable `spa: true` for:** React Router, Next.js, Vue Router, Nuxt, SvelteKit, Angular
+
+**Keep `spa: false` for:** Traditional multi-page apps, static sites, WordPress
+
+**Hash routing (`#/path`) NOT supported** - use History API routing.
+
+## Token Management
+
+- Found in: Dashboard → Web Analytics → Manage site
+- **Not secrets** - domain-locked, safe to expose in HTML
+- Each site gets unique token
+
+## Environment Config
+
+```typescript
+// Only load in production
+if (process.env.NODE_ENV === 'production') {
+  // Load beacon
+}
+```
+
+Or use environment-specific tokens via env vars.
+
+## Verify Installation
+
+1. DevTools Network → filter `cloudflareinsights` → see `beacon.min.js` + data request
+2. No CSP/CORS errors in console
+3. Dashboard shows pageviews after 5-10 min delay
+
+## Rules (Plan-dependent)
+
+Configure in dashboard for:
+- **Sample rate** - reduce collection % for high-traffic
+- **Path-based** - different behavior per route
+- **Host-based** - separate tracking per domain
+
+## Data Retention
+
+- 6 months rolling window
+- 1-hour bucket granularity
+- No raw export, dashboard only

package/skills/cloudflare-deploy/references/web-analytics/gotchas.md

@@ -0,0 +1,82 @@
+# Web Analytics Gotchas
+
+## Critical Issues
+
+### SPA Navigation Not Tracked
+
+**Symptom:** Only initial pageload counted  
+**Fix:** Add `spa: true`:
+```html
+<script data-cf-beacon='{"token": "TOKEN", "spa": true}' ...></script>
+```
+
+### CSP Blocking Beacon
+
+**Symptom:** Console error "Refused to load script"  
+**Fix:** Allow both domains:
+```
+script-src 'self' https://static.cloudflareinsights.com https://cloudflareinsights.com;
+```
+
+### Hash-Based Routing Unsupported
+
+**Symptom:** `#/path` URLs not tracked  
+**Fix:** Migrate to History API (`BrowserRouter`, not `HashRouter`). No workaround for hash routing.
+
+### No Data Appearing
+
+**Causes & Fixes:**
+1. **Delay** - Wait 5-15 minutes
+2. **Wrong token** - Verify matches dashboard exactly
+3. **Script blocked** - Check DevTools Network tab for beacon.min.js
+4. **Domain mismatch** - Dashboard site must match actual URL
+
+### Auto-Injection Fails
+
+**Cause:** `Cache-Control: no-transform` header  
+**Fix:** Remove `no-transform` or install beacon manually
+
+### Duplicate Pageviews
+
+**Cause:** Multiple beacon scripts  
+**Fix:** Keep only one beacon per page
+
+## Configuration Issues
+
+| Issue | Fix |
+|-------|-----|
+| 10-site limit reached | Delete old sites or proxy through CF (unlimited) |
+| Token not recognized | Use exact alphanumeric token from dashboard |
+
+## Framework-Specific
+
+### Next.js Hydration Warning
+
+```tsx
+<script suppressHydrationWarning ... />
+```
+
+### Gatsby Window Undefined
+
+Use `gatsby-browser.js` to load client-side only.
+
+## Limits
+
+| Resource | Limit |
+|----------|-------|
+| Non-proxied sites | 10 |
+| Proxied sites | Unlimited |
+| Data retention | 6 months |
+| Ingestion delay | 5-10 min |
+| API access | None (dashboard only) |
+
+## When NOT to Use Web Analytics
+
+Use alternatives if you need:
+- Custom event tracking
+- Real-time data
+- User-level tracking
+- Conversion funnels
+- Data export/API access
+
+**Web Analytics excels at:** Core Web Vitals, basic traffic, privacy compliance, free unlimited pageviews.