memory-journal-mcp 7.7.1 → 8.0.0

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

@@ -0,0 +1,240 @@
+# D1 Patterns & Best Practices
+
+## Pagination
+
+```typescript
+async function getUsers({ page, pageSize }: { page: number; pageSize: number }, env: Env) {
+  const offset = (page - 1) * pageSize
+  const [countResult, dataResult] = await env.DB.batch([
+    env.DB.prepare('SELECT COUNT(*) as total FROM users'),
+    env.DB.prepare('SELECT * FROM users ORDER BY created_at DESC LIMIT ? OFFSET ?').bind(
+      pageSize,
+      offset
+    ),
+  ])
+  return {
+    data: dataResult.results,
+    total: countResult.results[0].total,
+    page,
+    pageSize,
+    totalPages: Math.ceil(countResult.results[0].total / pageSize),
+  }
+}
+```
+
+## Conditional Queries
+
+```typescript
+async function searchUsers(filters: { name?: string; email?: string; active?: boolean }, env: Env) {
+  const conditions: string[] = [],
+    params: (string | number | boolean | null)[] = []
+  if (filters.name) {
+    conditions.push('name LIKE ?')
+    params.push(`%${filters.name}%`)
+  }
+  if (filters.email) {
+    conditions.push('email = ?')
+    params.push(filters.email)
+  }
+  if (filters.active !== undefined) {
+    conditions.push('active = ?')
+    params.push(filters.active ? 1 : 0)
+  }
+  const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : ''
+  return await env.DB.prepare(`SELECT * FROM users ${whereClause}`)
+    .bind(...params)
+    .all()
+}
+```
+
+## Bulk Insert
+
+```typescript
+async function bulkInsertUsers(users: Array<{ name: string; email: string }>, env: Env) {
+  const stmt = env.DB.prepare('INSERT INTO users (name, email) VALUES (?, ?)')
+  const batch = users.map((user) => stmt.bind(user.name, user.email))
+  return await env.DB.batch(batch)
+}
+```
+
+## Caching with KV
+
+```typescript
+async function getCachedUser(userId: number, env: { DB: D1Database; CACHE: KVNamespace }) {
+  const cacheKey = `user:${userId}`
+  const cached = await env.CACHE?.get(cacheKey, 'json')
+  if (cached) return cached
+  const user = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first()
+  if (user) await env.CACHE?.put(cacheKey, JSON.stringify(user), { expirationTtl: 300 })
+  return user
+}
+```
+
+## Query Optimization
+
+```typescript
+// ✅ Use indexes in WHERE clauses
+const users = await env.DB.prepare('SELECT * FROM users WHERE email = ?').bind(email).all()
+
+// ✅ Limit result sets
+const recentPosts = await env.DB.prepare(
+  'SELECT * FROM posts ORDER BY created_at DESC LIMIT 100'
+).all()
+
+// ✅ Use batch() for multiple independent queries
+const [user, posts, comments] = await env.DB.batch([
+  env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId),
+  env.DB.prepare('SELECT * FROM posts WHERE user_id = ?').bind(userId),
+  env.DB.prepare('SELECT * FROM comments WHERE user_id = ?').bind(userId),
+])
+
+// ❌ Avoid N+1 queries
+for (const post of posts) {
+  const author = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(post.user_id).first() // Bad: multiple round trips
+}
+
+// ✅ Use JOINs instead
+const postsWithAuthors = await env.DB.prepare(
+  `
+  SELECT posts.*, users.name as author_name
+  FROM posts
+  JOIN users ON posts.user_id = users.id
+`
+).all()
+```
+
+## Multi-Tenant SaaS
+
+```typescript
+// Each tenant gets own database
+export default {
+  async fetch(request: Request, env: { [key: `TENANT_${string}`]: D1Database }) {
+    const tenantId = request.headers.get('X-Tenant-ID')
+    const data = await env[`TENANT_${tenantId}`].prepare('SELECT * FROM records').all()
+    return Response.json(data.results)
+  },
+}
+```
+
+## Session Storage
+
+```typescript
+async function createSession(userId: number, token: string, env: Env) {
+  const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString()
+  return await env.DB.prepare('INSERT INTO sessions (user_id, token, expires_at) VALUES (?, ?, ?)')
+    .bind(userId, token, expiresAt)
+    .run()
+}
+
+async function validateSession(token: string, env: Env) {
+  return await env.DB.prepare(
+    'SELECT s.*, u.email FROM sessions s JOIN users u ON s.user_id = u.id WHERE s.token = ? AND s.expires_at > CURRENT_TIMESTAMP'
+  )
+    .bind(token)
+    .first()
+}
+```
+
+## Analytics/Events
+
+```typescript
+async function logEvent(event: { type: string; userId?: number; metadata: object }, env: Env) {
+  return await env.DB.prepare('INSERT INTO events (type, user_id, metadata) VALUES (?, ?, ?)')
+    .bind(event.type, event.userId || null, JSON.stringify(event.metadata))
+    .run()
+}
+
+async function getEventStats(startDate: string, endDate: string, env: Env) {
+  return await env.DB.prepare(
+    'SELECT type, COUNT(*) as count FROM events WHERE timestamp BETWEEN ? AND ? GROUP BY type ORDER BY count DESC'
+  )
+    .bind(startDate, endDate)
+    .all()
+}
+```
+
+## Read Replication Pattern (Paid Plans)
+
+```typescript
+interface Env {
+  DB: D1Database
+  DB_REPLICA: D1Database
+}
+
+export default {
+  async fetch(request: Request, env: Env) {
+    if (request.method === 'GET') {
+      // Reads: use replica for lower latency
+      const users = await env.DB_REPLICA.prepare('SELECT * FROM users WHERE active = 1').all()
+      return Response.json(users.results)
+    }
+
+    if (request.method === 'POST') {
+      const { name, email } = await request.json()
+      const result = await env.DB.prepare('INSERT INTO users (name, email) VALUES (?, ?)')
+        .bind(name, email)
+        .run()
+
+      // Read-after-write: use primary for consistency (replication lag <100ms-2s)
+      const user = await env.DB.prepare('SELECT * FROM users WHERE id = ?')
+        .bind(result.meta.last_row_id)
+        .first()
+      return Response.json(user, { status: 201 })
+    }
+  },
+}
+```
+
+**Use replicas for**: Analytics dashboards, search results, public queries (eventual consistency OK)  
+**Use primary for**: Read-after-write, financial transactions, authentication (consistency required)
+
+## Sessions API Pattern (Paid Plans)
+
+```typescript
+// Migration with long-running session (up to 15 min)
+async function runMigration(env: Env) {
+  const session = env.DB.withSession({ timeout: 600 }) // 10 min
+  try {
+    await session.prepare('CREATE INDEX idx_users_email ON users(email)').run()
+    await session.prepare('CREATE INDEX idx_posts_user ON posts(user_id)').run()
+    await session.prepare('ANALYZE').run()
+  } finally {
+    session.close() // Always close to prevent leaks
+  }
+}
+
+// Bulk transformation with batching
+async function transformLargeDataset(env: Env) {
+  const session = env.DB.withSession({ timeout: 900 }) // 15 min max
+  try {
+    const BATCH_SIZE = 1000
+    let offset = 0
+    while (true) {
+      const rows = await session
+        .prepare('SELECT id, data FROM legacy LIMIT ? OFFSET ?')
+        .bind(BATCH_SIZE, offset)
+        .all()
+      if (rows.results.length === 0) break
+      const updates = rows.results.map((row) =>
+        session
+          .prepare('UPDATE legacy SET new_data = ? WHERE id = ?')
+          .bind(transform(row.data), row.id)
+      )
+      await session.batch(updates)
+      offset += BATCH_SIZE
+    }
+  } finally {
+    session.close()
+  }
+}
+```
+
+## Time Travel & Backups
+
+```bash
+wrangler d1 time-travel restore <db-name> --timestamp="2024-01-15T14:30:00Z"  # Point-in-time
+wrangler d1 time-travel info <db-name>  # List restore points (7 days free, 30 days paid)
+wrangler d1 export <db-name> --remote --output=./backup.sql  # Full export
+wrangler d1 export <db-name> --remote --no-schema --output=./data.sql  # Data only
+wrangler d1 execute <db-name> --remote --file=./backup.sql  # Import
+```

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

@@ -0,0 +1,42 @@
+# Cloudflare DDoS Protection
+
+Autonomous, always-on protection against DDoS attacks across L3/4 and L7.
+
+## Protection Types
+
+- **HTTP DDoS (L7)**: Protects HTTP/HTTPS traffic, phase `ddos_l7`, zone/account level
+- **Network DDoS (L3/4)**: UDP/SYN/DNS floods, phase `ddos_l4`, account level only
+- **Adaptive DDoS**: Learns 7-day baseline, detects deviations, 4 profile types (Origins, User-Agents, Locations, Protocols)
+
+## Plan Availability
+
+| Feature             | Free  | Pro   | Business | Enterprise | Enterprise Advanced |
+| ------------------- | ----- | ----- | -------- | ---------- | ------------------- |
+| HTTP DDoS (L7)      | ✓     | ✓     | ✓        | ✓          | ✓                   |
+| Network DDoS (L3/4) | ✓     | ✓     | ✓        | ✓          | ✓                   |
+| Override rules      | 1     | 1     | 1        | 1          | 10                  |
+| Custom expressions  | ✗     | ✗     | ✗        | ✗          | ✓                   |
+| Log action          | ✗     | ✗     | ✗        | ✗          | ✓                   |
+| Adaptive DDoS       | ✗     | ✗     | ✗        | ✓          | ✓                   |
+| Alert filters       | Basic | Basic | Basic    | Advanced   | Advanced            |
+
+## Actions & Sensitivity
+
+- **Actions**: `block`, `managed_challenge`, `challenge`, `log` (Enterprise Advanced only)
+- **Sensitivity**: `default` (high), `medium`, `low`, `eoff` (essentially off)
+- **Override**: By category/tag or individual rule ID
+- **Scope**: Zone-level overrides take precedence over account-level
+
+## Reading Order
+
+| File                                   | Purpose                                                   | Start Here If...                                            |
+| -------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------- |
+| [configuration.md](./configuration.md) | Dashboard setup, rule structure, adaptive profiles        | You're setting up DDoS protection for the first time        |
+| [api.md](./api.md)                     | API endpoints, SDK usage, ruleset ID discovery            | You're automating configuration or need programmatic access |
+| [patterns.md](./patterns.md)           | Protection strategies, defense-in-depth, dynamic response | You need implementation patterns or layered security        |
+| [gotchas.md](./gotchas.md)             | False positives, tuning, error handling                   | You're troubleshooting or optimizing existing protection    |
+
+## See Also
+
+- [waf](../waf/) - Application-layer security rules
+- [bot-management](../bot-management/) - Bot detection and mitigation

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

@@ -0,0 +1,158 @@
+# DDoS API
+
+## Endpoints
+
+### HTTP DDoS (L7)
+
+```typescript
+// Zone-level
+PUT / zones / { zoneId } / rulesets / phases / ddos_l7 / entrypoint
+GET / zones / { zoneId } / rulesets / phases / ddos_l7 / entrypoint
+
+// Account-level (Enterprise Advanced)
+PUT / accounts / { accountId } / rulesets / phases / ddos_l7 / entrypoint
+GET / accounts / { accountId } / rulesets / phases / ddos_l7 / entrypoint
+```
+
+### Network DDoS (L3/4)
+
+```typescript
+// Account-level only
+PUT / accounts / { accountId } / rulesets / phases / ddos_l4 / entrypoint
+GET / accounts / { accountId } / rulesets / phases / ddos_l4 / entrypoint
+```
+
+## TypeScript SDK
+
+**SDK Version**: Requires `cloudflare` >= 3.0.0 for ruleset phase methods.
+
+```typescript
+import Cloudflare from 'cloudflare'
+
+const client = new Cloudflare({ apiToken: process.env.CLOUDFLARE_API_TOKEN })
+
+// STEP 1: Discover managed ruleset ID (required for overrides)
+const allRulesets = await client.rulesets.list({ zone_id: zoneId })
+const ddosRuleset = allRulesets.result.find((r) => r.kind === 'managed' && r.phase === 'ddos_l7')
+if (!ddosRuleset) throw new Error('DDoS managed ruleset not found')
+const managedRulesetId = ddosRuleset.id
+
+// STEP 2: Get current HTTP DDoS configuration
+const entrypointRuleset = await client.zones.rulesets.phases.entrypoint.get('ddos_l7', {
+  zone_id: zoneId,
+})
+
+// STEP 3: Update HTTP DDoS ruleset with overrides
+await client.zones.rulesets.phases.entrypoint.update('ddos_l7', {
+  zone_id: zoneId,
+  rules: [
+    {
+      action: 'execute',
+      expression: 'true',
+      action_parameters: {
+        id: managedRulesetId, // From discovery step
+        overrides: {
+          sensitivity_level: 'medium',
+          action: 'managed_challenge',
+        },
+      },
+    },
+  ],
+})
+
+// Network DDoS (account level, L3/4)
+const l4Rulesets = await client.rulesets.list({ account_id: accountId })
+const l4DdosRuleset = l4Rulesets.result.find((r) => r.kind === 'managed' && r.phase === 'ddos_l4')
+const l4Ruleset = await client.accounts.rulesets.phases.entrypoint.get('ddos_l4', {
+  account_id: accountId,
+})
+```
+
+## Alert Configuration
+
+```typescript
+interface DDoSAlertConfig {
+  name: string
+  enabled: boolean
+  alert_type:
+    | 'http_ddos_attack_alert'
+    | 'layer_3_4_ddos_attack_alert'
+    | 'advanced_http_ddos_attack_alert'
+    | 'advanced_layer_3_4_ddos_attack_alert'
+  filters?: {
+    zones?: string[]
+    hostnames?: string[]
+    requests_per_second?: number
+    packets_per_second?: number
+    megabits_per_second?: number
+    ip_prefixes?: string[] // CIDR
+    ip_addresses?: string[]
+    protocols?: string[]
+  }
+  mechanisms: {
+    email?: Array<{ id: string }>
+    webhooks?: Array<{ id: string }>
+    pagerduty?: Array<{ id: string }>
+  }
+}
+
+// Create alert
+await fetch(`https://api.cloudflare.com/client/v4/accounts/${accountId}/alerting/v3/policies`, {
+  method: 'POST',
+  headers: {
+    Authorization: `Bearer ${apiToken}`,
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify(alertConfig),
+})
+```
+
+## Typed Override Examples
+
+```typescript
+// Override by category
+interface CategoryOverride {
+  action: 'execute'
+  expression: string
+  action_parameters: {
+    id: string
+    overrides: {
+      categories?: Array<{
+        category: 'http-flood' | 'http-anomaly' | 'udp-flood' | 'syn-flood'
+        sensitivity_level?: 'default' | 'medium' | 'low' | 'eoff'
+        action?: 'block' | 'managed_challenge' | 'challenge' | 'log'
+      }>
+    }
+  }
+}
+
+// Override by rule ID
+interface RuleOverride {
+  action: 'execute'
+  expression: string
+  action_parameters: {
+    id: string
+    overrides: {
+      rules?: Array<{
+        id: string
+        action?: 'block' | 'managed_challenge' | 'challenge' | 'log'
+        sensitivity_level?: 'default' | 'medium' | 'low' | 'eoff'
+      }>
+    }
+  }
+}
+
+// Example: Override specific adaptive rule
+const adaptiveOverride: RuleOverride = {
+  action: 'execute',
+  expression: 'true',
+  action_parameters: {
+    id: managedRulesetId,
+    overrides: {
+      rules: [{ id: '...adaptive-origins-rule-id...', sensitivity_level: 'low' }],
+    },
+  },
+}
+```
+
+See [patterns.md](./patterns.md) for complete implementation patterns.

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

@@ -0,0 +1,94 @@
+# 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)
+5. Enable Adaptive DDoS toggle (Enterprise/Enterprise Advanced, requires 7 days traffic history)
+
+## Rule Structure
+
+```typescript
+interface DDoSOverride {
+  description: string
+  rules: Array<{
+    action: 'execute'
+    expression: string // Custom expression (Enterprise Advanced) or "true" for all
+    action_parameters: {
+      id: string // Managed ruleset ID (discover via api.md)
+      overrides: {
+        sensitivity_level?: 'default' | 'medium' | 'low' | 'eoff'
+        action?: 'block' | 'managed_challenge' | 'challenge' | 'log' // log = Enterprise Advanced only
+        categories?: Array<{
+          category: string // e.g., "http-flood", "udp-flood"
+          sensitivity_level?: string
+        }>
+        rules?: Array<{
+          id: string
+          action?: string
+          sensitivity_level?: string
+        }>
+      }
+    }
+  }>
+}
+```
+
+## Expression Availability
+
+| Plan                | Custom Expressions | Example                                                  |
+| ------------------- | ------------------ | -------------------------------------------------------- |
+| Free/Pro/Business   | ✗                  | Use `"true"` only                                        |
+| Enterprise          | ✗                  | Use `"true"` only                                        |
+| Enterprise Advanced | ✓                  | `ip.src in {...}`, `http.request.uri.path matches "..."` |
+
+## 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)
+
+## Override Precedence
+
+Multiple override layers apply in this order (higher precedence wins):
+
+```
+Zone-level > Account-level
+Individual Rule > Category > Global sensitivity/action
+```
+
+**Example**: Zone rule for `/api/*` overrides account-level global settings.
+
+## Adaptive DDoS Profiles
+
+**Availability**: Enterprise, Enterprise Advanced  
+**Learning period**: 7 days of traffic history required
+
+| Profile Type    | Description                          | Detects                                 |
+| --------------- | ------------------------------------ | --------------------------------------- |
+| **Origins**     | Traffic patterns per origin server   | Anomalous requests to specific origins  |
+| **User-Agents** | Traffic patterns per User-Agent      | Malicious/anomalous user agent strings  |
+| **Locations**   | Traffic patterns per geo-location    | Attacks from specific countries/regions |
+| **Protocols**   | Traffic patterns per protocol (L3/4) | Protocol-specific flood attacks         |
+
+Configure by targeting specific adaptive rule IDs via API (see api.md#typed-override-examples).
+
+## 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/references/ddos/gotchas.md

@@ -0,0 +1,114 @@
+# DDoS Gotchas
+
+## Common Errors
+
+### "False positives blocking legitimate traffic"
+
+**Cause**: Sensitivity too high, wrong action, or missing exceptions  
+**Solution**:
+
+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. Query flagged requests via GraphQL Analytics API to identify patterns
+
+### "Attacks getting through"
+
+**Cause**: Sensitivity too low or wrong action  
+**Solution**: Increase to `default` sensitivity and use `block` action:
+
+```typescript
+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)  
+**Solution**: Wait for baseline to establish, check dashboard for adaptive rule status
+
+### "Zone override ignored"
+
+**Cause**: Account overrides conflict with zone 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  
+**Solution**: Use `managed_challenge` with low sensitivity for testing
+
+### "Rule limit exceeded"
+
+**Cause**: Too many override rules (Free/Pro/Business: 1, Enterprise Advanced: 10)  
+**Solution**: Combine conditions in single expression using `and`/`or`
+
+### "Cannot override rule"
+
+**Cause**: Rule is read-only  
+**Solution**: Check API response for read-only indicator, use different rule
+
+### "Cannot disable DDoS protection"
+
+**Cause**: DDoS managed rulesets cannot be fully disabled (always-on protection)  
+**Solution**: Set `sensitivity_level: "eoff"` for minimal mitigation
+
+### "Expression not allowed"
+
+**Cause**: Custom expressions require Enterprise Advanced plan  
+**Solution**: Use `expression: "true"` for all traffic, or upgrade plan
+
+### "Managed ruleset not found"
+
+**Cause**: Zone/account doesn't have DDoS managed ruleset, or incorrect phase  
+**Solution**: Verify ruleset exists via `client.rulesets.list()`, check phase name (`ddos_l7` or `ddos_l4`)
+
+## API Error Codes
+
+| Error Code | Message                   | Cause                            | Solution                                            |
+| ---------- | ------------------------- | -------------------------------- | --------------------------------------------------- |
+| 10000      | Authentication error      | Invalid/missing API token        | Check token has DDoS permissions                    |
+| 81000      | Ruleset validation failed | Invalid rule structure           | Verify `action_parameters.id` is managed ruleset ID |
+| 81020      | Expression not allowed    | Custom expressions on wrong plan | Use `"true"` or upgrade to Enterprise Advanced      |
+| 81021      | Rule limit exceeded       | Too many override rules          | Reduce rules or upgrade (Enterprise Advanced: 10)   |
+| 81022      | Invalid sensitivity level | Wrong sensitivity value          | Use: `default`, `medium`, `low`, `eoff`             |
+| 81023      | Invalid action            | Wrong action for plan            | Enterprise Advanced only: `log` action              |
+
+## Limits
+
+| Resource/Limit           | Free/Pro/Business | Enterprise | Enterprise Advanced |
+| ------------------------ | ----------------- | ---------- | ------------------- |
+| Override rules per zone  | 1                 | 1          | 10                  |
+| Custom expressions       | ✗                 | ✗          | ✓                   |
+| Log action               | ✗                 | ✗          | ✓                   |
+| Adaptive DDoS            | ✗                 | ✓          | ✓                   |
+| Traffic history required | -                 | 7 days     | 7 days              |
+
+## 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.