memory-journal-mcp 7.7.1 → 8.0.0

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

@@ -0,0 +1,220 @@
+# DDoS Protection Patterns
+
+## Allowlist Trusted IPs
+
+```typescript
+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' },
+      },
+    },
+  ],
+}
+
+await client.accounts.rulesets.phases.entrypoint.update('ddos_l7', {
+  account_id: accountId,
+  ...config,
+})
+```
+
+## Route-specific Sensitivity
+
+```typescript
+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',
+}
+
+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
+
+async function setProtectionLevel(
+  zoneId: string,
+  level: ProtectionLevel,
+  rulesetId: string,
+  client: Cloudflare
+) {
+  const settings = levelConfig[level]
+  return client.zones.rulesets.phases.entrypoint.update('ddos_l7', {
+    zone_id: zoneId,
+    rules: [
+      {
+        expression: 'true',
+        action: 'execute',
+        action_parameters: {
+          id: rulesetId,
+          overrides: { action: settings.action, sensitivity_level: settings.sensitivity },
+        },
+      },
+    ],
+  })
+}
+```
+
+## Dynamic Response to Attacks
+
+```typescript
+interface Env {
+  CLOUDFLARE_API_TOKEN: string
+  ZONE_ID: string
+  KV: 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.put(`attack:${Date.now()}`, JSON.stringify(attackData), { expirationTtl: 86400 })
+      const recentAttacks = await getRecentAttacks(env.KV)
+      if (recentAttacks.length > 5) {
+        await setProtectionLevel(env.ZONE_ID, ProtectionLevel.HIGH, managedRulesetId, client)
+        return new Response('Protection increased')
+      }
+    }
+    return new Response('OK')
+  },
+  async scheduled(event: ScheduledEvent, env: Env): Promise<void> {
+    const recentAttacks = await getRecentAttacks(env.KV)
+    if (recentAttacks.length === 0)
+      await setProtectionLevel(env.ZONE_ID, ProtectionLevel.MEDIUM, managedRulesetId, client)
+  },
+}
+```
+
+## Multi-rule Tiered Protection (Enterprise Advanced)
+
+```typescript
+const config = {
+  description: 'Multi-tier DDoS protection',
+  rules: [
+    {
+      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' },
+      },
+    },
+    {
+      expression: 'cf.bot_management.verified_bot',
+      action: 'execute',
+      action_parameters: {
+        id: managedRulesetId,
+        overrides: { sensitivity_level: 'medium', action: 'managed_challenge' },
+      },
+    },
+    {
+      expression: 'ip.src in $trusted_ips',
+      action: 'execute',
+      action_parameters: { id: managedRulesetId, overrides: { sensitivity_level: 'low' } },
+    },
+  ],
+}
+```
+
+## Defense in Depth
+
+Layered security stack: DDoS + WAF + Rate Limiting + Bot Management.
+
+```typescript
+// Layer 1: DDoS (volumetric attacks)
+await client.zones.rulesets.phases.entrypoint.update('ddos_l7', {
+  zone_id: zoneId,
+  rules: [
+    {
+      expression: 'true',
+      action: 'execute',
+      action_parameters: { id: ddosRulesetId, overrides: { sensitivity_level: 'medium' } },
+    },
+  ],
+})
+
+// Layer 2: WAF (exploit protection)
+await client.zones.rulesets.phases.entrypoint.update('http_request_firewall_managed', {
+  zone_id: zoneId,
+  rules: [{ expression: 'true', action: 'execute', action_parameters: { id: wafRulesetId } }],
+})
+
+// Layer 3: Rate Limiting (abuse prevention)
+await client.zones.rulesets.phases.entrypoint.update('http_ratelimit', {
+  zone_id: zoneId,
+  rules: [
+    {
+      expression: 'http.request.uri.path eq "/api/login"',
+      action: 'block',
+      ratelimit: { characteristics: ['ip.src'], period: 60, requests_per_period: 5 },
+    },
+  ],
+})
+
+// Layer 4: Bot Management (automation detection)
+await client.zones.rulesets.phases.entrypoint.update('http_request_sbfm', {
+  zone_id: zoneId,
+  rules: [{ expression: 'cf.bot_management.score lt 30', action: 'managed_challenge' }],
+})
+```
+
+## Cache Strategy for DDoS Mitigation
+
+Exclude query strings from cache key to counter randomized query parameter attacks.
+
+```typescript
+const cacheRule = {
+  expression: 'http.request.uri.path matches "^/api/"',
+  action: 'set_cache_settings',
+  action_parameters: {
+    cache: true,
+    cache_key: {
+      ignore_query_strings_order: true,
+      custom_key: { query_string: { exclude: { all: true } } },
+    },
+  },
+}
+
+await client.zones.rulesets.phases.entrypoint.update('http_request_cache_settings', {
+  zone_id: zoneId,
+  rules: [cacheRule],
+})
+```
+
+**Rationale**: Attackers randomize query strings (`?random=123456`) to bypass cache. Excluding query params ensures cache hits absorb attack traffic.
+
+See [configuration.md](./configuration.md) for rule structure details.

package/skills/cloudflare/references/decision-trees.md

@@ -0,0 +1,95 @@
+## Quick Decision Trees
+
+### "I need to run code"
+
+```
+Need to run code?
+├─ Serverless functions at the edge → workers/
+├─ Full-stack web app with Git deploys → pages/
+├─ Stateful coordination/real-time → durable-objects/
+├─ Long-running multi-step jobs → workflows/
+├─ Run containers → containers/
+├─ Multi-tenant (customers deploy code) → workers-for-platforms/
+├─ Scheduled tasks (cron) → cron-triggers/
+├─ Lightweight edge logic (modify HTTP) → snippets/
+├─ Process Worker execution events (logs/observability) → tail-workers/
+└─ Optimize latency to backend infrastructure → smart-placement/
+```
+
+### "I need to store data"
+
+```
+Need storage?
+├─ Key-value (config, sessions, cache) → kv/
+├─ Relational SQL → d1/ (SQLite) or hyperdrive/ (existing Postgres/MySQL)
+├─ Object/file storage (S3-compatible) → r2/
+├─ Message queue (async processing) → queues/
+├─ Vector embeddings (AI/semantic search) → vectorize/
+├─ Strongly-consistent per-entity state → durable-objects/ (DO storage)
+├─ Secrets management → secrets-store/
+├─ Streaming ETL to R2 → pipelines/
+└─ Persistent cache (long-term retention) → cache-reserve/
+```
+
+### "I need AI/ML"
+
+```
+Need AI?
+├─ Run inference (LLMs, embeddings, images) → workers-ai/
+├─ Vector database for RAG/search → vectorize/
+├─ Build stateful AI agents → agents-sdk/
+├─ Gateway for any AI provider (caching, routing) → ai-gateway/
+└─ AI-powered search widget → ai-search/
+```
+
+### "I need networking/connectivity"
+
+```
+Need networking?
+├─ Expose local service to internet → tunnel/
+├─ TCP/UDP proxy (non-HTTP) → spectrum/
+├─ WebRTC TURN server → turn/
+├─ Private network connectivity → network-interconnect/
+├─ Optimize routing → argo-smart-routing/
+├─ Optimize latency to backend (not user) → smart-placement/
+└─ Real-time video/audio → realtimekit/ or realtime-sfu/
+```
+
+### "I need security"
+
+```
+Need security?
+├─ Web Application Firewall → waf/
+├─ DDoS protection → ddos/
+├─ Bot detection/management → bot-management/
+├─ API protection → api-shield/
+├─ CAPTCHA alternative → turnstile/
+└─ Credential leak detection → waf/ (managed ruleset)
+```
+
+### "I need media/content"
+
+```
+Need media?
+├─ Image optimization/transformation → images/
+├─ Video streaming/encoding → stream/
+├─ Browser automation/screenshots → browser-rendering/
+└─ Third-party script management → zaraz/
+```
+
+### "I need analytics/metrics data"
+
+```
+Need analytics?
+├─ Query across all Cloudflare products (HTTP, Workers, DNS, etc.) → graphql-api/
+├─ Custom high-cardinality metrics from Workers → analytics-engine/
+├─ Client-side (RUM) performance data → web-analytics/
+├─ Workers Logs and real-time debugging → observability/
+└─ Raw logs (Logpush to external tools) → Cloudflare docs
+```
+
+### "I need infrastructure-as-code"
+
+```
+Need IaC? → pulumi/ (Pulumi), terraform/ (Terraform), or api/ (REST API)
+```

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

@@ -0,0 +1,79 @@
+# 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
+
+**Billing:** Charged by request, GB-month storage, and rowsRead/rowsWritten for SQL operations
+
+## 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> {
+    const result = this.sql
+      .exec(
+        'INSERT INTO data VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = value + 1 RETURNING value',
+        'counter',
+        1
+      )
+      .one()
+    return result?.value || 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)
+
+## Reading Order
+
+**New to DO storage:** configuration.md → api.md → patterns.md → gotchas.md  
+**Building features:** patterns.md → api.md → gotchas.md  
+**Debugging issues:** gotchas.md → api.md  
+**Writing tests:** testing.md
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - wrangler.jsonc migrations, SQLite vs KV setup, RPC binding
+- [api.md](./api.md) - SQL exec/cursors, KV methods, storage options, transactions, alarms, PITR
+- [patterns.md](./patterns.md) - Schema migrations, caching, rate limiting, batch processing, parent-child coordination
+- [gotchas.md](./gotchas.md) - Concurrency gates, INTEGER precision, transaction rules, SQL limits
+- [testing.md](./testing.md) - vitest-pool-workers setup, testing DOs with SQL/alarms/PITR
+
+## 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/references/do-storage/api.md

@@ -0,0 +1,107 @@
+# 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", "..."]
+
+// Manual iteration
+const iter = cursor[Symbol.iterator]()
+const first = iter.next() // { value: {...}, done: false }
+
+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 })
+```
+
+### Storage Options
+
+| Option             | Methods        | Effect                                                        | Use Case                                                         |
+| ------------------ | -------------- | ------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `allowConcurrency` | get, list      | Skip input gate; allow concurrent requests during read        | Read-heavy metrics that don't need strict consistency            |
+| `noCache`          | get, put, list | Skip in-memory cache; always read from disk                   | Rarely-accessed data or testing storage directly                 |
+| `allowUnconfirmed` | put, delete    | Return before write confirms (still protected by output gate) | Non-critical writes where latency matters more than confirmation |
+
+## 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/references/do-storage/configuration.md

@@ -0,0 +1,114 @@
+# DO Storage Configuration
+
+## SQLite-backed (Recommended)
+
+**wrangler.jsonc:**
+
+```jsonc
+{
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_sqlite_classes": ["Counter", "Session", "RateLimiter"],
+    },
+  ],
+}
+```
+
+**Migration lifecycle:** Migrations run once per deployment. Existing DO instances get new storage backend on next invocation. Renaming/removing classes requires `renamed_classes` or `deleted_classes` entries.
+
+## 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)
+
+    // Modern RPC: call methods directly (recommended)
+    const result = await stub.someMethod()
+    return Response.json(result)
+
+    // Legacy: forward request (still works)
+    // return stub.fetch(request);
+  },
+}
+```
+
+## CPU Limits
+
+```jsonc
+{
+  "limits": {
+    "cpu_ms": 300000, // 5 minutes (default 30s)
+  },
+}
+```
+
+## 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
+    })
+  }
+}
+```