@bcelep/capint 0.4.2 → 0.7.0

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

@@ -0,0 +1,208 @@
+# Binding Gotchas and Troubleshooting
+
+## Critical: Global Scope Mutation
+
+### ❌ THE #1 GOTCHA: Caching env in Global Scope
+
+```typescript
+// ❌ DANGEROUS - env cached at deploy time
+const apiKey = env.API_KEY;  // ERROR: env not available in global scope
+
+export default {
+  async fetch(request: Request, env: Env) {
+    // Uses undefined or stale value!
+  }
+}
+```
+
+**Why it breaks:**
+- `env` not available in global scope
+- If using workarounds, secrets may not update without redeployment
+- Leads to "Cannot read property 'X' of undefined" errors
+
+**✅ Always access env per-request:**
+```typescript
+export default {
+  async fetch(request: Request, env: Env) {
+    const apiKey = env.API_KEY;  // Fresh every request
+  }
+}
+```
+
+## Common Errors
+
+### "env.MY_KV is undefined"
+
+**Cause:** Name mismatch or not configured  
+**Solution:** Check wrangler.jsonc (case-sensitive), run `npx wrangler types`, verify `npx wrangler kv namespace list`
+
+### "Property 'MY_KV' does not exist on type 'Env'"
+
+**Cause:** Types not generated  
+**Solution:** `npx wrangler types`
+
+### "preview_id is required for --remote"
+
+**Cause:** Missing preview binding  
+**Solution:** Add `"preview_id": "dev-id"` or use `npx wrangler dev` (local mode)
+
+### "Secret updated but Worker still uses old value"
+
+**Cause:** Cached in global scope or not redeployed  
+**Solution:** Avoid global caching, redeploy after secret change
+
+### "KV get() returns null for existing key"
+
+**Cause:** Eventual consistency (60s), wrong namespace, wrong environment  
+**Solution:**
+```bash
+# Check key exists
+npx wrangler kv key get --binding=MY_KV "your-key"
+
+# Verify namespace ID
+npx wrangler kv namespace list
+
+# Check environment
+npx wrangler deployments list
+```
+
+### "D1 database not found"
+
+**Solution:** `npx wrangler d1 list`, verify ID in wrangler.jsonc
+
+### "Service binding returns 'No such service'"
+
+**Cause:** Target Worker not deployed, name mismatch, environment mismatch  
+**Solution:**
+```bash
+# List deployed Workers
+npx wrangler deployments list --name=target-worker
+
+# Check service binding config
+cat wrangler.jsonc | grep -A2 services
+
+# Deploy target first
+cd ../target-worker && npx wrangler deploy
+```
+
+### "Rate limit exceeded" on KV writes
+
+**Cause:** >1 write/second per key  
+**Solution:** Use different keys, Durable Objects, or Queues
+
+## Type Safety Gotchas
+
+### Missing @cloudflare/workers-types
+
+**Error:** `Cannot find name 'Request'`  
+**Solution:** `npm install -D @cloudflare/workers-types`, add to tsconfig.json `"types"`
+
+### Binding Type Mismatches
+
+```typescript
+// ❌ Wrong - KV returns string | null
+const value: string = await env.MY_KV.get('key');
+
+// ✅ Handle null
+const value = await env.MY_KV.get('key');
+if (!value) return new Response('Not found', { status: 404 });
+```
+
+## Environment Gotchas
+
+### Wrong Environment Deployed
+
+**Solution:** Check `npx wrangler deployments list`, use `--env` flag
+
+### Secrets Not Per-Environment
+
+**Solution:** Set per environment: `npx wrangler secret put API_KEY --env staging`
+
+## Development Gotchas
+
+**wrangler dev vs deploy:**
+- dev: Uses `preview_id` or local bindings, secrets not available
+- deploy: Uses production `id`, secrets available
+
+**Access secrets in dev:** `npx wrangler dev --remote`  
+**Persist local data:** `npx wrangler dev --persist`
+
+## Performance Gotchas
+
+### Sequential Binding Calls
+
+```typescript
+// ❌ Slow
+const user = await env.DB.prepare('...').first();
+const config = await env.MY_KV.get('config');
+
+// ✅ Parallel
+const [user, config] = await Promise.all([
+  env.DB.prepare('...').first(),
+  env.MY_KV.get('config')
+]);
+```
+
+## Security Gotchas
+
+**❌ Secrets in logs:** `console.log('Key:', env.API_KEY)` - visible in dashboard  
+**✅** `console.log('Key:', env.API_KEY ? '***' : 'missing')`
+
+**❌ Exposing env:** `return Response.json(env)` - exposes all bindings  
+**✅** Never return env object in responses
+
+## Limits Reference
+
+| Resource | Limit | Impact | Plan |
+|----------|-------|--------|------|
+| **Bindings per Worker** | 64 total | All binding types combined | All |
+| **Environment variables** | 64 max, 5KB each | Per Worker | All |
+| **Secret size** | 1KB | Per secret | All |
+| **KV key size** | 512 bytes | UTF-8 encoded | All |
+| **KV value size** | 25 MB | Per value | All |
+| **KV writes per key** | 1/second | Per key; exceeding = 429 error | All |
+| **KV list() results** | 1000 keys | Per call; use cursor for more | All |
+| **KV operations** | 1000 reads/day | Free tier only | Free |
+| **R2 object size** | 5 TB | Per object | All |
+| **R2 operations** | 1M Class A/month free | Writes | All |
+| **D1 database size** | 10 GB | Per database | All |
+| **D1 rows per query** | 100,000 | Result set limit | All |
+| **D1 databases** | 10 | Free tier | Free |
+| **Queue batch size** | 100 messages | Per consumer batch | All |
+| **Queue message size** | 128 KB | Per message | All |
+| **Service binding calls** | Unlimited | Counts toward CPU time | All |
+| **Durable Objects** | 1M requests/month free | First 1M | Free |
+
+## Debugging Tips
+
+```bash
+# Check configuration
+npx wrangler deploy --dry-run       # Validate config without deploying
+npx wrangler kv namespace list      # List KV namespaces
+npx wrangler secret list            # List secrets (not values)
+npx wrangler deployments list       # Recent deployments
+
+# Inspect bindings
+npx wrangler kv key list --binding=MY_KV
+npx wrangler kv key get --binding=MY_KV "key-name"
+npx wrangler r2 object get my-bucket/file.txt
+npx wrangler d1 execute my-db --command="SELECT * FROM sqlite_master"
+
+# Test locally
+npx wrangler dev                  # Local mode
+npx wrangler dev --remote         # Production bindings
+npx wrangler dev --persist        # Persist data across restarts
+
+# Verify types
+npx wrangler types
+cat .wrangler/types/runtime.d.ts | grep "interface Env"
+
+# Debug specific binding issues
+npx wrangler tail                 # Stream logs in real-time
+npx wrangler tail --format=pretty # Formatted logs
+```
+
+## See Also
+
+- [Workers Limits](https://developers.cloudflare.com/workers/platform/limits/)
+- [Wrangler Commands](https://developers.cloudflare.com/workers/wrangler/commands/)

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

@@ -0,0 +1,200 @@
+# 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,94 @@
+# 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,169 @@
+# 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.