memory-journal-mcp 8.0.1 → 9.1.0

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

@@ -1,205 +0,0 @@
-# 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

@@ -1,95 +0,0 @@
-# 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

@@ -1,175 +0,0 @@
-# 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

@@ -1,175 +0,0 @@
-# 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