@namch/agent-assistant 1.0.0

package/skills/cloudflare-expert/references/ddos/configuration.md

@@ -0,0 +1,67 @@
+# DDoS Configuration
+
+## Dashboard Setup
+
+1. Navigate to Security > DDoS
+2. Select HTTP DDoS or Network-layer DDoS
+3. Configure sensitivity & action per ruleset/category/rule
+4. Apply overrides with optional expressions (Enterprise Advanced)
+
+## Rule Structure
+
+```typescript
+interface DDoSOverride {
+  description: string;
+  rules: Array<{
+    action: "execute";
+    expression: string; // Filter traffic, "true" for all
+    action_parameters: {
+      id: string; // Managed ruleset ID
+      overrides: {
+        sensitivity_level?: "default" | "medium" | "low" | "eoff";
+        action?: "block" | "managed_challenge" | "challenge" | "log";
+        categories?: Array<{ // Override by category
+          category: string; // e.g., "http-flood", "udp-flood"
+          sensitivity_level?: string;
+        }>;
+        rules?: Array<{ // Override by rule ID
+          id: string;
+          action?: string;
+          sensitivity_level?: string;
+        }>;
+      };
+    };
+  }>;
+}
+```
+
+## Sensitivity Mapping
+
+| UI | API | Threshold |
+|----|-----|-----------|
+| High | `default` | Most aggressive |
+| Medium | `medium` | Balanced |
+| Low | `low` | Less aggressive |
+| Essentially Off | `eoff` | Minimal mitigation |
+
+## Common Categories
+
+- `http-flood`, `http-anomaly` (L7)
+- `udp-flood`, `syn-flood`, `dns-flood` (L3/4)
+
+## Adaptive Rules
+
+Configure by targeting specific rule IDs. Check dashboard for IDs:
+- HTTP: origins, user-agents, locations
+- L4: protocols
+
+Requires 7 days of traffic history to learn baseline.
+
+## Alerting
+
+Configure via Notifications:
+- Alert types: `http_ddos_attack_alert`, `layer_3_4_ddos_attack_alert`, `advanced_*` variants
+- Filters: zones, hostnames, RPS/PPS/Mbps thresholds, IPs, protocols
+- Mechanisms: email, webhooks, PagerDuty
+
+See [api.md](./api.md#alert-configuration) for API examples.

package/skills/cloudflare-expert/references/ddos/gotchas.md

@@ -0,0 +1,114 @@
+# DDoS Gotchas
+
+## False Positives
+
+**Symptom**: Legitimate traffic blocked/challenged
+
+**Diagnosis**:
+```typescript
+// Query GraphQL API for flagged requests
+const query = `
+  query {
+    viewer {
+      zones(filter: { zoneTag: "${zoneId}" }) {
+        httpRequestsAdaptiveGroups(
+          filter: { ruleId: "${ruleId}", action: "log" }
+          limit: 100
+          orderBy: [datetime_DESC]
+        ) {
+          dimensions {
+            clientCountryName
+            clientRequestHTTPHost
+            clientRequestPath
+            userAgent
+          }
+          count
+        }
+      }
+    }
+  }
+`;
+```
+
+**Fix**:
+1. Lower sensitivity for specific rule/category
+2. Use `log` action first to validate (Enterprise Advanced)
+3. Add exception with custom expression (e.g., allowlist IPs)
+4. Reduce category sensitivity: `{ category: "http-flood", sensitivity_level: "low" }`
+
+## Attacks Getting Through
+
+**Cause**: Sensitivity too low, wrong action
+
+**Fix**:
+```typescript
+// Increase to default (high) sensitivity
+const config = {
+  rules: [{
+    expression: "true",
+    action: "execute",
+    action_parameters: {
+      id: managedRulesetId,
+      overrides: { sensitivity_level: "default", action: "block" },
+    },
+  }],
+};
+```
+
+## Adaptive Rules Not Working
+
+**Cause**: Insufficient traffic history (needs 7 days)
+
+**Fix**: Wait for baseline to establish, check dashboard for adaptive rule status
+
+## Zone vs Account Override Conflict
+
+**Issue**: Account overrides ignored when zone has overrides
+
+**Solution**: Configure at zone level OR remove zone overrides to use account-level
+
+## Log Action Not Available
+
+**Cause**: Not on Enterprise Advanced DDoS plan
+
+**Workaround**: Use `managed_challenge` with low sensitivity for testing
+
+## Rule Limit Exceeded
+
+**Plans**:
+- Free/Pro/Business: 1 override rule only
+- Enterprise Advanced: Up to 10 rules
+
+**Workaround**: Combine conditions in single expression using `and`/`or`
+
+## Read-only Managed Rules
+
+**Issue**: Some rules cannot be overridden
+
+**Check**: API response indicates if rule is read-only
+
+## Always-on Protection
+
+**Reality**: DDoS managed rulesets cannot be fully disabled
+
+**Minimum**: Set `sensitivity_level: "eoff"` for minimal mitigation
+
+## Tuning Strategy
+
+1. Start with `log` action + `medium` sensitivity
+2. Monitor for 24-48 hours
+3. Identify false positives, add exceptions
+4. Gradually increase to `default` sensitivity
+5. Change action from `log` → `managed_challenge` → `block`
+6. Document all adjustments
+
+## Best Practices
+
+- Test during low-traffic periods
+- Use zone-level for per-site tuning
+- Reference IP lists for easier management
+- Set appropriate alert thresholds (avoid noise)
+- Combine with WAF for layered defense
+- Avoid over-tuning (keep config simple)
+
+See [patterns.md](./patterns.md) for progressive rollout examples.

package/skills/cloudflare-expert/references/ddos/patterns.md

@@ -0,0 +1,158 @@
+# DDoS Protection Patterns
+
+## Allowlist Trusted IPs
+
+```typescript
+// Account-level override with custom expression
+const config = {
+  description: "Allowlist trusted IPs",
+  rules: [{
+    expression: "ip.src in { 203.0.113.0/24 192.0.2.1 }",
+    action: "execute",
+    action_parameters: {
+      id: managedRulesetId,
+      overrides: { sensitivity_level: "eoff" }, // Effectively off
+    },
+  }],
+};
+
+await fetch(
+  `https://api.cloudflare.com/client/v4/accounts/${accountId}/rulesets/phases/ddos_l7/entrypoint`,
+  { method: "PUT", headers: { Authorization: `Bearer ${apiToken}`, "Content-Type": "application/json" }, body: JSON.stringify(config) }
+);
+```
+
+## Route-specific Sensitivity
+
+```typescript
+// Lower sensitivity for bursty API endpoints
+const config = {
+  description: "Route-specific protection",
+  rules: [
+    {
+      expression: "not http.request.uri.path matches \"^/api/\"",
+      action: "execute",
+      action_parameters: {
+        id: managedRulesetId,
+        overrides: { sensitivity_level: "default", action: "block" },
+      },
+    },
+    {
+      expression: "http.request.uri.path matches \"^/api/\"",
+      action: "execute",
+      action_parameters: {
+        id: managedRulesetId,
+        overrides: { sensitivity_level: "low", action: "managed_challenge" },
+      },
+    },
+  ],
+};
+```
+
+## Progressive Enhancement
+
+```typescript
+enum ProtectionLevel { MONITORING = "monitoring", LOW = "low", MEDIUM = "medium", HIGH = "high" }
+
+async function setProtectionLevel(zoneId: string, level: ProtectionLevel, managedRulesetId: string, apiToken: string) {
+  const levelConfig = {
+    [ProtectionLevel.MONITORING]: { action: "log", sensitivity: "eoff" },
+    [ProtectionLevel.LOW]: { action: "managed_challenge", sensitivity: "low" },
+    [ProtectionLevel.MEDIUM]: { action: "managed_challenge", sensitivity: "medium" },
+    [ProtectionLevel.HIGH]: { action: "block", sensitivity: "default" },
+  } as const;
+
+  const settings = levelConfig[level];
+  const config = {
+    description: `DDoS protection level: ${level}`,
+    rules: [{
+      expression: "true",
+      action: "execute",
+      action_parameters: {
+        id: managedRulesetId,
+        overrides: { action: settings.action, sensitivity_level: settings.sensitivity },
+      },
+    }],
+  };
+
+  return fetch(/* ... */);
+}
+
+// Gradual rollout: Week 1 MONITORING → Week 2 LOW → Week 3 MEDIUM → Week 4 HIGH
+```
+
+## Dynamic Response to Attacks
+
+```typescript
+// Worker adjusts settings based on attack patterns
+interface Env {
+  CLOUDFLARE_API_TOKEN: string;
+  ZONE_ID: string;
+  KV_NAMESPACE: KVNamespace;
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    if (request.url.includes("/attack-detected")) {
+      const attackData = await request.json();
+      await env.KV_NAMESPACE.put(`attack:${Date.now()}`, JSON.stringify(attackData), { expirationTtl: 86400 });
+
+      const recentAttacks = await getRecentAttacks(env.KV_NAMESPACE);
+      if (recentAttacks.length > 5) {
+        await increaseProtection(env.ZONE_ID, "managed-ruleset-id", env.CLOUDFLARE_API_TOKEN);
+        return new Response("Protection increased", { status: 200 });
+      }
+    }
+    return new Response("OK");
+  },
+
+  // Cron: auto-decrease after quiet period
+  async scheduled(event: ScheduledEvent, env: Env): Promise<void> {
+    const recentAttacks = await getRecentAttacks(env.KV_NAMESPACE);
+    if (recentAttacks.length === 0) {
+      await normalizeProtection(env.ZONE_ID, "managed-ruleset-id", env.CLOUDFLARE_API_TOKEN);
+    }
+  },
+};
+```
+
+## Multi-rule Tiered Protection (Enterprise Advanced)
+
+```typescript
+// Up to 10 rules with different conditions
+const config = {
+  description: "Multi-tier DDoS protection",
+  rules: [
+    { // Strictest for unknown traffic
+      expression: "not ip.src in $known_ips and not cf.bot_management.score gt 30",
+      action: "execute",
+      action_parameters: {
+        id: managedRulesetId,
+        overrides: { sensitivity_level: "default", action: "block" },
+      },
+    },
+    { // Medium for verified bots
+      expression: "cf.bot_management.verified_bot",
+      action: "execute",
+      action_parameters: {
+        id: managedRulesetId,
+        overrides: { sensitivity_level: "medium", action: "managed_challenge" },
+      },
+    },
+    { // Low for trusted IPs
+      expression: "ip.src in $trusted_ips",
+      action: "execute",
+      action_parameters: {
+        id: managedRulesetId,
+        overrides: { sensitivity_level: "low" },
+      },
+    },
+  ],
+};
+```
+
+## Defense in Depth
+
+Combine DDoS with WAF, Rate Limiting, Bot Management. Layer protections at different levels.
+
+See [configuration.md](./configuration.md) for rule structure details.

package/skills/cloudflare-expert/references/do-storage/README.md

@@ -0,0 +1,62 @@
+# Cloudflare Durable Objects Storage
+
+Persistent storage API for Durable Objects with SQLite and KV backends, PITR, and automatic concurrency control.
+
+## Overview
+
+DO Storage provides:
+- SQLite-backed (recommended) or KV-backed
+- SQL API + synchronous/async KV APIs
+- Automatic input/output gates (race-free)
+- 30-day point-in-time recovery (PITR)
+- Transactions and alarms
+
+**Use cases:** Stateful coordination, real-time collaboration, counters, sessions, rate limiters
+
+## Quick Start
+
+```typescript
+export class Counter extends DurableObject {
+  sql: SqlStorage;
+  
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env);
+    this.sql = ctx.storage.sql;
+    this.sql.exec('CREATE TABLE IF NOT EXISTS data(key TEXT PRIMARY KEY, value INTEGER)');
+  }
+  
+  async increment(): Promise<number> {
+    this.sql.exec('INSERT OR REPLACE INTO data VALUES (?, ?) RETURNING value', 'counter', 
+      (this.sql.exec('SELECT value FROM data WHERE key = ?', 'counter').one()?.value || 0) + 1);
+  }
+}
+```
+
+## Storage Backends
+
+| Backend | Create Method | APIs | PITR |
+|---------|---------------|------|------|
+| SQLite (recommended) | `new_sqlite_classes` | SQL + sync KV + async KV | ✅ |
+| KV (legacy) | `new_classes` | async KV only | ❌ |
+
+## Core APIs
+
+- **SQL API** (`ctx.storage.sql`): Full SQLite with extensions (FTS5, JSON, math)
+- **Sync KV** (`ctx.storage.kv`): Synchronous key-value (SQLite only)
+- **Async KV** (`ctx.storage`): Asynchronous key-value (both backends)
+- **Transactions** (`transactionSync()`, `transaction()`)
+- **PITR** (`getBookmarkForTime()`, `onNextSessionRestoreBookmark()`)
+- **Alarms** (`setAlarm()`, `alarm()` handler)
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - wrangler.jsonc migrations, SQLite vs KV setup
+- [api.md](./api.md) - SQL exec/cursors, KV methods, transactions, alarms, PITR
+- [patterns.md](./patterns.md) - Schema migrations, caching, rate limiting, batch processing
+- [gotchas.md](./gotchas.md) - Concurrency gates, transaction rules, SQL limits, async pitfalls
+
+## See Also
+
+- [durable-objects](../durable-objects/) - DO fundamentals and coordination patterns
+- [workers](../workers/) - Worker runtime for DO stubs
+- [d1](../d1/) - Shared database alternative to per-DO storage

package/skills/cloudflare-expert/references/do-storage/api.md

@@ -0,0 +1,89 @@
+# DO Storage API Reference
+
+## SQL API
+
+```typescript
+const cursor = this.sql.exec('SELECT * FROM users WHERE email = ?', email);
+for (let row of cursor) {} // Objects: { id, name, email }
+cursor.toArray(); cursor.one(); // Single row (throws if != 1)
+for (let row of cursor.raw()) {} // Arrays: [1, "Alice", "..."]
+cursor.columnNames; // ["id", "name", "email"]
+cursor.rowsRead; cursor.rowsWritten; // Billing
+
+type User = { id: number; name: string; email: string };
+const user = this.sql.exec<User>('...', userId).one();
+```
+
+## Sync KV API (SQLite only)
+
+```typescript
+this.ctx.storage.kv.get("counter"); // undefined if missing
+this.ctx.storage.kv.put("counter", 42);
+this.ctx.storage.kv.put("user", { name: "Alice", age: 30 });
+this.ctx.storage.kv.delete("counter"); // true if existed
+
+for (let [key, value] of this.ctx.storage.kv.list()) {}
+
+// List options: start, prefix, reverse, limit
+this.ctx.storage.kv.list({ start: "user:", prefix: "user:", reverse: true, limit: 100 });
+```
+
+## Async KV API (Both backends)
+
+```typescript
+await this.ctx.storage.get("key"); // Single
+await this.ctx.storage.get(["key1", "key2"]); // Multiple (max 128)
+await this.ctx.storage.put("key", value); // Single
+await this.ctx.storage.put({ "key1": "v1", "key2": { nested: true } }); // Multiple (max 128)
+await this.ctx.storage.delete("key");
+await this.ctx.storage.delete(["key1", "key2"]);
+await this.ctx.storage.list({ prefix: "user:", limit: 100 });
+
+// Options: allowConcurrency, noCache, allowUnconfirmed
+await this.ctx.storage.get("key", { allowConcurrency: true, noCache: true });
+await this.ctx.storage.put("key", value, { allowUnconfirmed: true, noCache: true });
+```
+
+## Transactions
+
+```typescript
+// Sync (SQL/sync KV only)
+this.ctx.storage.transactionSync(() => {
+  this.sql.exec('UPDATE accounts SET balance = balance - ? WHERE id = ?', 100, 1);
+  this.sql.exec('UPDATE accounts SET balance = balance + ? WHERE id = ?', 100, 2);
+  return "result";
+});
+
+// Async
+await this.ctx.storage.transaction(async () => {
+  const value = await this.ctx.storage.get("counter");
+  await this.ctx.storage.put("counter", value + 1);
+  if (value > 100) this.ctx.storage.rollback(); // Explicit rollback
+});
+```
+
+## Point-in-Time Recovery
+
+```typescript
+await this.ctx.storage.getCurrentBookmark();
+await this.ctx.storage.getBookmarkForTime(Date.now() - 2 * 24 * 60 * 60 * 1000);
+await this.ctx.storage.onNextSessionRestoreBookmark(bookmark);
+this.ctx.abort(); // Restart to apply; bookmarks lexically comparable (earlier < later)
+```
+
+## Alarms
+
+```typescript
+await this.ctx.storage.setAlarm(Date.now() + 60000); // Timestamp or Date
+await this.ctx.storage.getAlarm();
+await this.ctx.storage.deleteAlarm();
+
+async alarm() { await this.doScheduledWork(); }
+```
+
+## Misc
+
+```typescript
+await this.ctx.storage.deleteAll(); // Atomic for SQLite; alarm NOT included
+this.ctx.storage.sql.databaseSize; // Bytes
+```

package/skills/cloudflare-expert/references/do-storage/configuration.md

@@ -0,0 +1,116 @@
+# DO Storage Configuration
+
+## SQLite-backed (Recommended)
+
+**wrangler.jsonc:**
+```jsonc
+{
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_sqlite_classes": ["Counter", "Session", "RateLimiter"]
+    }
+  ]
+}
+```
+
+**wrangler.toml:**
+```toml
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["Counter", "Session"]
+```
+
+## KV-backed (Legacy)
+
+**wrangler.jsonc:**
+```jsonc
+{
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_classes": ["OldCounter"]
+    }
+  ]
+}
+```
+
+## TypeScript Setup
+
+```typescript
+export class MyDurableObject extends DurableObject {
+  sql: SqlStorage;
+  
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env);
+    this.sql = ctx.storage.sql;
+    
+    // Initialize schema
+    this.sql.exec(`
+      CREATE TABLE IF NOT EXISTS users(
+        id INTEGER PRIMARY KEY,
+        name TEXT NOT NULL,
+        email TEXT UNIQUE
+      );
+    `);
+  }
+}
+
+// Binding
+interface Env {
+  MY_DO: DurableObjectNamespace;
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const id = env.MY_DO.idFromName('singleton');
+    const stub = env.MY_DO.get(id);
+    return stub.fetch(request);
+  }
+}
+```
+
+## CPU Limits
+
+```jsonc
+{
+  "limits": {
+    "cpu_ms": 300000  // 5 minutes (default 30s)
+  }
+}
+```
+
+```toml
+[limits]
+cpu_ms = 300_000
+```
+
+## Location Control
+
+```typescript
+// Jurisdiction (GDPR/FedRAMP)
+const euNamespace = env.MY_DO.jurisdiction("eu");
+const id = euNamespace.newUniqueId();
+const stub = euNamespace.get(id);
+
+// Location hint (best effort)
+const stub = env.MY_DO.get(id, { locationHint: "enam" });
+// Hints: wnam, enam, sam, weur, eeur, apac, oc, afr, me
+```
+
+## Initialization
+
+```typescript
+export class Counter extends DurableObject {
+  value: number;
+  
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env);
+    
+    // Block concurrent requests during init
+    ctx.blockConcurrencyWhile(async () => {
+      this.value = (await ctx.storage.get("value")) || 0;
+    });
+  }
+}
+```

package/skills/cloudflare-expert/references/do-storage/gotchas.md

@@ -0,0 +1,93 @@
+# DO Storage Gotchas & Troubleshooting
+
+## Concurrency Gates
+
+**Input gate:** No new events while storage op pending (except storage completions)
+**Output gate:** Network messages held until storage writes confirm
+
+```typescript
+// ✅ NO RACE: Auto serialization
+async getUniqueNumber() {
+  let val = await this.ctx.storage.get("counter"); // Other requests blocked
+  await this.ctx.storage.put("counter", val + 1);
+  return val;
+}
+
+// ❌ RACE: Concurrent calls from same event
+async handler() {
+  const [v1, v2] = await Promise.all([this.getUniqueNumber(), this.getUniqueNumber()]); // v1 === v2!
+}
+
+// ✅ SAFE: Response waits for write confirm; if write fails, response discarded & restart
+async increment() {
+  let val = await this.ctx.storage.get("counter");
+  this.ctx.storage.put("counter", val + 1); // Don't await
+  return new Response(String(val));
+}
+```
+
+## Transaction Rules
+
+```typescript
+// ❌ WRONG: Direct SQL statements
+this.sql.exec('BEGIN TRANSACTION');
+
+// ✅ CORRECT: Use transactionSync() or async transaction()
+this.ctx.storage.transactionSync(() => { this.sql.exec('UPDATE ...'); });
+await this.ctx.storage.transaction(async () => { await this.ctx.storage.put("key", value); });
+
+// ❌ WRONG: Async in transactionSync
+this.ctx.storage.transactionSync(async () => { await fetch(...); }); // Error!
+```
+
+## Limits
+
+**SQL:** Max cols/table: 100; string/BLOB/row: 2MB; statement: 100KB; params: 100; LIKE/GLOB: 50B
+**Storage:** SQLite: 10GB/object, 2MB key+value; KV: Unlimited storage, key 2KiB, value 128KiB
+
+## TypeScript Type Safety
+
+```typescript
+// ❌ Types don't validate at runtime
+type User = { id: number; name: string };
+const user = this.sql.exec<User>('SELECT id FROM users WHERE id = ?', id).one(); // Only has { id }!
+
+// ✅ Query must match type
+const user = this.sql.exec<User>('SELECT id, name FROM users WHERE id = ?', id).one();
+```
+
+## Alarm Persistence
+
+```typescript
+// ❌ deleteAll() doesn't delete alarms
+await this.ctx.storage.deleteAll(); // Alarm remains!
+
+// ✅ Delete alarm explicitly
+await this.ctx.storage.deleteAlarm();
+await this.ctx.storage.deleteAll();
+```
+
+## Auto Caching & Bypass
+
+```typescript
+// Built-in cache makes simple code fast
+async getUniqueNumber() {
+  let val = await this.ctx.storage.get("counter"); // Cached after first
+  await this.ctx.storage.put("counter", val + 1);  // Instant cache write
+  return val;
+}
+
+// Bypass opts: allowConcurrency, noCache, allowUnconfirmed
+await this.ctx.storage.get("key", { allowConcurrency: true, noCache: true });
+```
+
+## Common Errors & Best Practices
+
+**Slow perf:** Use sync KV API (`ctx.storage.kv`) vs async  
+**Races:** Check concurrent calls from same event (not protected)  
+**High billing:** Check `rowsRead`/`rowsWritten`; verify unused objects call `deleteAll()`  
+**Overload:** Single DO soft limit ~1K req/sec; shard
+
+**Do:** Use SQLite-backed; sync KV for simple key-value; don't await writes unnecessarily (output gate protects); use `blockConcurrencyWhile()` for init; delete alarms AND storage when cleaning
+
+**Don't:** Use SQL transaction statements directly; initiate concurrent storage ops from same event; assume TypeScript types validate at runtime