memory-journal-mcp 7.7.0 → 8.0.0

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

@@ -0,0 +1,205 @@
+# Binding Patterns and Best Practices
+
+## Service Binding Patterns
+
+### RPC via Service Bindings
+
+```typescript
+// auth-worker
+export default {
+  async fetch(request: Request, env: Env) {
+    const token = request.headers.get('Authorization')
+    return new Response(JSON.stringify({ valid: await validateToken(token) }))
+  },
+}
+
+// api-worker
+const response = await env.AUTH_SERVICE.fetch(
+  new Request('https://fake-host/validate', {
+    headers: { Authorization: token },
+  })
+)
+```
+
+**Why RPC?** Zero latency (same datacenter), no DNS, free, type-safe.
+
+**HTTP vs Service:**
+
+```typescript
+// ❌ HTTP (slow, paid, cross-region latency)
+await fetch('https://auth-worker.example.com/validate')
+
+// ✅ Service binding (fast, free, same isolate)
+await env.AUTH_SERVICE.fetch(new Request('https://fake-host/validate'))
+```
+
+**URL doesn't matter:** Service bindings ignore hostname/protocol, routing happens via binding name.
+
+### Typed Service RPC
+
+```typescript
+// shared-types.ts
+export interface AuthRequest {
+  token: string
+}
+export interface AuthResponse {
+  valid: boolean
+  userId?: string
+}
+
+// auth-worker
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const body: AuthRequest = await request.json()
+    const response: AuthResponse = { valid: true, userId: '123' }
+    return Response.json(response)
+  },
+}
+
+// api-worker
+const response = await env.AUTH_SERVICE.fetch(
+  new Request('https://fake/validate', {
+    method: 'POST',
+    body: JSON.stringify({ token } satisfies AuthRequest),
+  })
+)
+const data: AuthResponse = await response.json()
+```
+
+## Secrets Management
+
+```bash
+# Set secret
+npx wrangler secret put API_KEY
+cat api-key.txt | npx wrangler secret put API_KEY
+npx wrangler secret put API_KEY --env staging
+```
+
+```typescript
+// Use secret
+const response = await fetch('https://api.example.com', {
+  headers: { Authorization: `Bearer ${env.API_KEY}` },
+})
+```
+
+**Never commit secrets:**
+
+```jsonc
+// ❌ NEVER
+{ "vars": { "API_KEY": "sk_live_abc123" } }
+```
+
+## Testing with Mock Bindings
+
+### Vitest Mock
+
+```typescript
+import { vi } from 'vitest'
+
+const mockKV: KVNamespace = {
+  get: vi.fn(async (key) => (key === 'test' ? 'value' : null)),
+  put: vi.fn(async () => {}),
+  delete: vi.fn(async () => {}),
+  list: vi.fn(async () => ({ keys: [], list_complete: true, cursor: '' })),
+  getWithMetadata: vi.fn(),
+} as unknown as KVNamespace
+
+const mockEnv: Env = { MY_KV: mockKV }
+const mockCtx: ExecutionContext = {
+  waitUntil: vi.fn(),
+  passThroughOnException: vi.fn(),
+}
+
+const response = await worker.fetch(new Request('http://localhost/test'), mockEnv, mockCtx)
+```
+
+## Binding Access Patterns
+
+### Lazy Access
+
+```typescript
+// ✅ Access only when needed
+if (url.pathname === '/cached') {
+  const cached = await env.MY_KV.get('data')
+  if (cached) return new Response(cached)
+}
+```
+
+### Parallel Access
+
+```typescript
+// ✅ Parallelize independent calls
+const [user, config, cache] = await Promise.all([
+  env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first(),
+  env.MY_KV.get('config'),
+  env.CACHE.get('data'),
+])
+```
+
+## Storage Selection
+
+### KV: CDN-Backed Reads
+
+```typescript
+const config = await env.MY_KV.get('app-config', { type: 'json' })
+```
+
+**Use when:** Read-heavy, <25MB, global distribution, eventual consistency OK  
+**Latency:** <10ms reads (cached), writes eventually consistent (60s)
+
+### D1: Relational Queries
+
+```typescript
+const results = await env.DB.prepare(
+  `
+  SELECT u.name, COUNT(o.id) FROM users u
+  LEFT JOIN orders o ON u.id = o.user_id GROUP BY u.id
+`
+).all()
+```
+
+**Use when:** Relational data, JOINs, ACID transactions  
+**Limits:** 10GB database size, 100k rows per query
+
+### R2: Large Objects
+
+```typescript
+const object = await env.MY_BUCKET.get('large-file.zip')
+return new Response(object.body)
+```
+
+**Use when:** Files >25MB, S3-compatible API needed  
+**Limits:** 5TB per object, unlimited storage
+
+### Durable Objects: Coordination
+
+```typescript
+const id = env.COUNTER.idFromName('global')
+const stub = env.COUNTER.get(id)
+await stub.fetch(new Request('https://fake/increment'))
+```
+
+**Use when:** Strong consistency, real-time coordination, WebSocket state  
+**Guarantees:** Single-threaded execution, transactional storage
+
+## Anti-Patterns
+
+**❌ Hardcoding credentials:** `const apiKey = 'sk_live_abc123'`  
+**✅** `npx wrangler secret put API_KEY`
+
+**❌ Using REST API:** `fetch('https://api.cloudflare.com/.../kv/...')`  
+**✅** `env.MY_KV.get('key')`
+
+**❌ Polling storage:** `setInterval(() => env.KV.get('config'), 1000)`  
+**✅** Use Durable Objects for real-time state
+
+**❌ Large data in vars:** `{ "vars": { "HUGE_CONFIG": "..." } }` (5KB max)  
+**✅** `env.MY_KV.put('config', data)`
+
+**❌ Caching env globally:** `const apiKey = env.API_KEY` outside fetch()  
+**✅** Access `env.API_KEY` per-request inside fetch()
+
+## See Also
+
+- [Service Bindings Docs](https://developers.cloudflare.com/workers/runtime-apis/bindings/service-bindings/)
+- [Miniflare Testing](https://miniflare.dev/)

package/skills/cloudflare/references/bot-management/README.md

@@ -0,0 +1,95 @@
+# Cloudflare Bot Management
+
+Enterprise-grade bot detection, protection, and mitigation using ML/heuristics, bot scores, JavaScript detections, and verified bot handling.
+
+## Overview
+
+Bot Management provides multi-tier protection:
+
+- **Free (Bot Fight Mode)**: Auto-blocks definite bots, no config
+- **Pro/Business (Super Bot Fight Mode)**: Configurable actions, static resource protection, analytics groupings
+- **Enterprise (Bot Management)**: Granular 1-99 scores, WAF integration, JA3/JA4 fingerprinting, Workers API, Advanced Analytics
+
+## Quick Start
+
+```txt
+# Dashboard: Security > Bots
+# Enterprise: Deploy rule template
+(cf.bot_management.score eq 1 and not cf.bot_management.verified_bot) → Block
+(cf.bot_management.score le 29 and not cf.bot_management.verified_bot) → Managed Challenge
+```
+
+## What Do You Need?
+
+```txt
+├─ Initial setup → configuration.md
+│   ├─ Free tier → "Bot Fight Mode"
+│   ├─ Pro/Business → "Super Bot Fight Mode"
+│   └─ Enterprise → "Bot Management for Enterprise"
+├─ Workers API integration → api.md
+├─ WAF rules → patterns.md
+├─ Debugging → gotchas.md
+└─ Analytics → api.md#bot-analytics
+```
+
+## Reading Order
+
+| Task                  | Files to Read             |
+| --------------------- | ------------------------- |
+| Enable bot protection | README → configuration.md |
+| Workers bot detection | README → api.md           |
+| WAF rule templates    | README → patterns.md      |
+| Debug bot issues      | gotchas.md                |
+| Advanced analytics    | api.md#bot-analytics      |
+
+## Core Concepts
+
+**Bot Scores**: 1-99 (1 = definitely automated, 99 = definitely human). Threshold: <30 indicates bot traffic. Enterprise gets granular 1-99; Pro/Business get groupings only.
+
+**Detection Engines**: Heuristics (known fingerprints, assigns score=1), ML (majority of detections, supervised learning on billions of requests), Anomaly Detection (optional, baseline traffic analysis), JavaScript Detections (headless browser detection).
+
+**Verified Bots**: Allowlisted good bots (search engines, AI crawlers) verified via reverse DNS or Web Bot Auth. Access via `cf.bot_management.verified_bot` or `cf.verified_bot_category`.
+
+## Platform Limits
+
+| Plan         | Bot Scores           | JA3/JA4 | Custom Rules | Analytics Retention        |
+| ------------ | -------------------- | ------- | ------------ | -------------------------- |
+| Free         | No (auto-block only) | No      | 5            | N/A (no analytics)         |
+| Pro/Business | Groupings only       | No      | 20/100       | 30 days (72h at a time)    |
+| Enterprise   | 1-99 granular        | Yes     | 1,000+       | 30 days (1 week at a time) |
+
+## Basic Patterns
+
+```typescript
+// Workers: Check bot score
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const botScore = request.cf?.botManagement?.score
+    if (botScore && botScore < 30 && !request.cf?.botManagement?.verifiedBot) {
+      return new Response('Bot detected', { status: 403 })
+    }
+    return fetch(request)
+  },
+}
+```
+
+```txt
+# WAF: Block definite bots
+(cf.bot_management.score eq 1 and not cf.bot_management.verified_bot)
+
+# WAF: Protect sensitive endpoints
+(cf.bot_management.score lt 50 and http.request.uri.path in {"/login" "/checkout"} and not cf.bot_management.verified_bot)
+```
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - Product tiers, WAF rule setup, JavaScript Detections, ML auto-updates
+- [api.md](./api.md) - Workers BotManagement interface, WAF fields, JA4 Signals
+- [patterns.md](./patterns.md) - E-commerce, API protection, mobile app allowlisting, SEO-friendly handling
+- [gotchas.md](./gotchas.md) - False positives/negatives, score=0 issues, JSD limitations, CSP requirements
+
+## See Also
+
+- [waf](../waf/) - WAF custom rules for bot enforcement
+- [workers](../workers/) - Workers request.cf.botManagement API
+- [api-shield](../api-shield/) - API-specific bot protection

package/skills/cloudflare/references/bot-management/api.md

@@ -0,0 +1,175 @@
+# Bot Management API
+
+## Workers: BotManagement Interface
+
+```typescript
+interface BotManagement {
+  score: number // 1-99 (Enterprise), 0 if not computed
+  verifiedBot: boolean // Is verified bot
+  staticResource: boolean // Serves static resource
+  ja3Hash: string // JA3 fingerprint (Enterprise, HTTPS only)
+  ja4: string // JA4 fingerprint (Enterprise, HTTPS only)
+  jsDetection?: {
+    passed: boolean // Passed JS detection (if enabled)
+  }
+  detectionIds: number[] // Heuristic detection IDs
+  corporateProxy?: boolean // From corporate proxy (Enterprise)
+}
+
+// DEPRECATED: Use botManagement.score instead
+// request.cf.clientTrustScore (legacy, duplicate of botManagement.score)
+
+// Access via request.cf
+import type { IncomingRequestCfProperties } from '@cloudflare/workers-types'
+
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const cf = request.cf as IncomingRequestCfProperties | undefined
+    const botMgmt = cf?.botManagement
+
+    if (!botMgmt) return fetch(request)
+    if (botMgmt.verifiedBot) return fetch(request) // Allow verified bots
+    if (botMgmt.score === 1) return new Response('Blocked', { status: 403 })
+    if (botMgmt.score < 30) return new Response('Challenge required', { status: 429 })
+
+    return fetch(request)
+  },
+}
+```
+
+## WAF Fields Reference
+
+```txt
+# Score fields
+cf.bot_management.score                    # 0-99 (0 = not computed)
+cf.bot_management.verified_bot             # boolean
+cf.bot_management.static_resource          # boolean
+cf.bot_management.ja3_hash                 # string (Enterprise)
+cf.bot_management.ja4                      # string (Enterprise)
+cf.bot_management.detection_ids            # array
+cf.bot_management.js_detection.passed      # boolean
+cf.bot_management.corporate_proxy          # boolean (Enterprise)
+cf.verified_bot_category                   # string
+
+# Workers equivalent
+request.cf.botManagement.score
+request.cf.botManagement.verifiedBot
+request.cf.botManagement.ja3Hash
+request.cf.botManagement.ja4
+request.cf.botManagement.jsDetection.passed
+request.cf.verifiedBotCategory
+```
+
+## JA4 Signals (Enterprise)
+
+```typescript
+import type { IncomingRequestCfProperties } from '@cloudflare/workers-types'
+
+interface JA4Signals {
+  // Ratios (0.0-1.0)
+  heuristic_ratio_1h?: number // Fraction flagged by heuristics
+  browser_ratio_1h?: number // Fraction from real browsers
+  cache_ratio_1h?: number // Fraction hitting cache
+  h2h3_ratio_1h?: number // Fraction using HTTP/2 or HTTP/3
+  // Ranks (relative position in distribution)
+  uas_rank_1h?: number // User-Agent diversity rank
+  paths_rank_1h?: number // Path diversity rank
+  reqs_rank_1h?: number // Request volume rank
+  ips_rank_1h?: number // IP diversity rank
+  // Quantiles (0.0-1.0, percentile in distribution)
+  reqs_quantile_1h?: number // Request volume quantile
+  ips_quantile_1h?: number // IP count quantile
+}
+
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const cf = request.cf as IncomingRequestCfProperties | undefined
+    const ja4Signals = cf?.ja4Signals as JA4Signals | undefined
+
+    if (!ja4Signals) return fetch(request) // Not available for HTTP or Worker routing
+
+    // Check for anomalous behavior
+    // High heuristic_ratio or low browser_ratio = suspicious
+    const heuristicRatio = ja4Signals.heuristic_ratio_1h ?? 0
+    const browserRatio = ja4Signals.browser_ratio_1h ?? 0
+
+    if (heuristicRatio > 0.5 || browserRatio < 0.3) {
+      return new Response('Suspicious traffic', { status: 403 })
+    }
+
+    return fetch(request)
+  },
+}
+```
+
+## Common Patterns
+
+See [patterns.md](./patterns.md) for Workers examples: mobile app allowlisting, corporate proxy exemption, datacenter detection, conditional delay, and more.
+
+## Bot Analytics
+
+### Access Locations
+
+- Dashboard: Security > Bots (old) or Security > Analytics > Bot analysis (new)
+- GraphQL API for programmatic access
+- Security Events & Security Analytics
+- Logpush/Logpull
+
+### Available Data
+
+- **Enterprise BM**: Bot scores (1-99), bot score source, distribution
+- **Pro/Business**: Bot groupings (automated, likely automated, likely human)
+- Top attributes: IPs, paths, user agents, countries
+- Detection sources: Heuristics, ML, AD, JSD
+- Verified bot categories
+
+### Time Ranges
+
+- **Enterprise BM**: Up to 1 week at a time, 30 days history
+- **Pro/Business**: Up to 72 hours at a time, 30 days history
+- Real-time in most cases, adaptive sampling (1-10% depending on volume)
+
+## Logpush Fields
+
+```txt
+BotScore              # 1-99 or 0 if not computed
+BotScoreSrc           # Detection engine (ML, Heuristics, etc.)
+BotTags               # Classification tags
+BotDetectionIDs       # Heuristic detection IDs
+```
+
+**BotScoreSrc values:**
+
+- `"Heuristics"` - Known fingerprint
+- `"Machine Learning"` - ML model
+- `"Anomaly Detection"` - Baseline anomaly
+- `"JS Detection"` - JavaScript check
+- `"Cloudflare Service"` - Zero Trust
+- `"Not Computed"` - Score = 0
+
+Access via Logpush (stream to cloud storage/SIEM), Logpull (API to fetch logs), or GraphQL API (query analytics data).
+
+## Testing with Miniflare
+
+Miniflare provides mock botManagement data for local development:
+
+**Default values:**
+
+- `score: 99` (human)
+- `verifiedBot: false`
+- `corporateProxy: false`
+- `ja3Hash: "25b4882c2bcb50cd6b469ff28c596742"`
+- `staticResource: false`
+- `detectionIds: []`
+
+**Override in tests:**
+
+```typescript
+import { getPlatformProxy } from 'wrangler'
+
+const { cf, dispose } = await getPlatformProxy()
+// cf.botManagement is frozen mock object
+expect(cf.botManagement.score).toBe(99)
+```
+
+For custom test data, mock request.cf in your test setup.

package/skills/cloudflare/references/bot-management/configuration.md

@@ -0,0 +1,175 @@
+# Bot Management Configuration
+
+## Product Tiers
+
+**Note:** Dashboard paths differ between old and new UI:
+
+- **New:** Security > Settings > Filter "Bot traffic"
+- **Old:** Security > Bots
+
+Both UIs access same settings.
+
+### Bot Score Groupings (Pro/Business)
+
+Pro/Business users see bot score groupings instead of granular 1-99 scores:
+
+| Score | Grouping         | Meaning                        |
+| ----- | ---------------- | ------------------------------ |
+| 0     | Not computed     | Bot Management didn't run      |
+| 1     | Automated        | Definite bot (heuristic match) |
+| 2-29  | Likely automated | Probably bot (ML detection)    |
+| 30-99 | Likely human     | Probably human                 |
+| N/A   | Verified bot     | Allowlisted good bot           |
+
+Enterprise plans get granular 1-99 scores for custom thresholds.
+
+### Bot Fight Mode (Free)
+
+- Auto-blocks definite bots (score=1), excludes verified bots by default
+- JavaScript Detections always enabled, no configuration options
+
+### Super Bot Fight Mode (Pro/Business)
+
+```txt
+Dashboard: Security > Bots > Configure
+- Definitely automated: Block/Challenge
+- Likely automated: Challenge/Allow
+- Verified bots: Allow (recommended)
+- Static resource protection: ON (may block mail clients)
+- JavaScript Detections: Optional
+```
+
+### Bot Management for Enterprise
+
+```txt
+Dashboard: Security > Bots > Configure > Auto-updates: ON (recommended)
+
+# Template 1: Block definite bots
+(cf.bot_management.score eq 1 and not cf.bot_management.verified_bot and not cf.bot_management.static_resource)
+Action: Block
+
+# Template 2: Challenge likely bots
+(cf.bot_management.score ge 2 and cf.bot_management.score le 29 and not cf.bot_management.verified_bot and not cf.bot_management.static_resource)
+Action: Managed Challenge
+```
+
+## JavaScript Detections Setup
+
+### Enable via Dashboard
+
+```txt
+Security > Bots > Configure Bot Management > JS Detections: ON
+
+Update CSP: script-src 'self' /cdn-cgi/challenge-platform/;
+```
+
+### Manual JS Injection (API)
+
+```html
+<script>
+  function jsdOnload() {
+    window.cloudflare.jsd.executeOnce({
+      callback: function (result) {
+        console.log('JSD:', result)
+      },
+    })
+  }
+</script>
+<script src="/cdn-cgi/challenge-platform/scripts/jsd/api.js?onload=jsdOnload" async></script>
+```
+
+**Use API for**: Selective deployment on specific pages  
+**Don't combine**: Zone-wide toggle + manual injection
+
+### WAF Rules for JSD
+
+```txt
+# NEVER use on first page visit (needs HTML page first)
+(not cf.bot_management.js_detection.passed and http.request.uri.path eq "/api/user/create" and http.request.method eq "POST" and not cf.bot_management.verified_bot)
+Action: Managed Challenge (always use Managed Challenge, not Block)
+```
+
+### Limitations
+
+- First request won't have JSD data (needs HTML page first)
+- Strips ETags from HTML responses
+- Not supported with CSP via `<meta>` tags
+- Websocket endpoints not supported
+- Native mobile apps won't pass
+- cf_clearance cookie: 15-minute lifespan, max 4096 bytes
+
+## \_\_cf_bm Cookie
+
+Cloudflare sets `__cf_bm` cookie to smooth bot scores across user sessions:
+
+- **Purpose:** Reduces false positives from score volatility
+- **Scope:** Per-domain, HTTP-only
+- **Lifespan:** Session duration
+- **Privacy:** No PII—only session classification
+- **Automatic:** No configuration required
+
+Bot scores for repeat visitors consider session history via this cookie.
+
+## Static Resource Protection
+
+**File Extensions**: ico, jpg, png, jpeg, gif, css, js, tif, tiff, bmp, pict, webp, svg, svgz, class, jar, txt, csv, doc, docx, xls, xlsx, pdf, ps, pls, ppt, pptx, ttf, otf, woff, woff2, eot, eps, ejs, swf, torrent, midi, mid, m3u8, m4a, mp3, ogg, ts  
+**Plus**: `/.well-known/` path (all files)
+
+```txt
+# Exclude static resources from bot rules
+(cf.bot_management.score lt 30 and not cf.bot_management.static_resource)
+```
+
+**WARNING**: May block mail clients fetching static images
+
+## JA3/JA4 Fingerprinting (Enterprise)
+
+```txt
+# Block specific attack fingerprint
+(cf.bot_management.ja3_hash eq "8b8e3d5e3e8b3d5e")
+
+# Allow mobile app by fingerprint
+(cf.bot_management.ja4 eq "your_mobile_app_fingerprint")
+```
+
+Only available for HTTPS/TLS traffic. Missing for Worker-routed traffic or HTTP requests.
+
+## Verified Bot Categories
+
+```txt
+# Allow search engines only
+(cf.verified_bot_category eq "Search Engine Crawler")
+
+# Block AI crawlers
+(cf.verified_bot_category eq "AI Crawler")
+Action: Block
+
+# Or use dashboard: Security > Settings > Bot Management > Block AI Bots
+```
+
+| Category                | String Value                 | Example                        |
+| ----------------------- | ---------------------------- | ------------------------------ |
+| AI Crawler              | `AI Crawler`                 | GPTBot, Claude-Web             |
+| AI Assistant            | `AI Assistant`               | Perplexity-User, DuckAssistBot |
+| AI Search               | `AI Search`                  | OAI-SearchBot                  |
+| Accessibility           | `Accessibility`              | Accessible Web Bot             |
+| Academic Research       | `Academic Research`          | Library of Congress            |
+| Advertising & Marketing | `Advertising & Marketing`    | Google Adsbot                  |
+| Aggregator              | `Aggregator`                 | Pinterest, Indeed              |
+| Archiver                | `Archiver`                   | Internet Archive, CommonCrawl  |
+| Feed Fetcher            | `Feed Fetcher`               | RSS/Podcast updaters           |
+| Monitoring & Analytics  | `Monitoring & Analytics`     | Uptime monitors                |
+| Page Preview            | `Page Preview`               | Facebook/Slack link preview    |
+| SEO                     | `Search Engine Optimization` | Google Lighthouse              |
+| Security                | `Security`                   | Vulnerability scanners         |
+| Social Media Marketing  | `Social Media Marketing`     | Brandwatch                     |
+| Webhooks                | `Webhooks`                   | Payment processors             |
+| Other                   | `Other`                      | Uncategorized bots             |
+
+## Best Practices
+
+- **ML Auto-Updates**: Enable on Enterprise for latest models
+- **Start with Managed Challenge**: Test before blocking
+- **Always exclude verified bots**: Use `not cf.bot_management.verified_bot`
+- **Exempt corporate proxies**: For B2B traffic via `cf.bot_management.corporate_proxy`
+- **Use static resource exception**: Improves performance, reduces overhead