opencodekit 0.15.4 → 0.15.5

package/dist/template/.opencode/skill/cloudflare/references/bot-management/api.md

@@ -0,0 +1,168 @@
+# 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)
+}
+
+// Access via request.cf
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const cf = request.cf as any;
+    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
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const cf = request.cf as any;
+    const ja4Signals = cf?.ja4Signals;
+    
+    if (!ja4Signals) return fetch(request); // Not available for HTTP or Worker routing
+    
+    // Check for anomalous behavior
+    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
+
+### Mobile App Pattern
+```typescript
+const MOBILE_APP_JA4 = 'your_mobile_app_ja4_fingerprint';
+
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const cf = request.cf as any;
+    const botMgmt = cf?.botManagement;
+    
+    if (botMgmt?.ja4 === MOBILE_APP_JA4) return fetch(request); // Allow mobile app
+    if (botMgmt?.score && botMgmt.score < 30) return new Response('Bot detected', { status: 403 });
+    
+    return fetch(request);
+  }
+};
+```
+
+### Corporate Proxy Exemption
+```typescript
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const cf = request.cf as any;
+    const botMgmt = cf?.botManagement;
+    
+    if (botMgmt?.corporateProxy) return fetch(request); // Exempt corporate proxy traffic
+    if (botMgmt?.score && botMgmt.score < 30 && !botMgmt.verifiedBot) {
+      return new Response('Bot detected', { status: 403 });
+    }
+    
+    return fetch(request);
+  }
+};
+```
+
+### Log Bot Data
+```typescript
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const cf = request.cf as any;
+    const botMgmt = cf?.botManagement;
+    
+    console.log({
+      score: botMgmt?.score,
+      verifiedBot: botMgmt?.verifiedBot,
+      ja3Hash: botMgmt?.ja3Hash,
+      ja4: botMgmt?.ja4,
+      detectionIds: botMgmt?.detectionIds,
+      jsDetection: botMgmt?.jsDetection?.passed,
+      corporateProxy: botMgmt?.corporateProxy,
+    });
+    
+    return fetch(request);
+  }
+};
+```
+
+## 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
+```
+
+Access via Logpush (stream to cloud storage/SIEM), Logpull (API to fetch logs), or GraphQL API (query analytics data).

package/dist/template/.opencode/skill/cloudflare/references/bot-management/configuration.md

@@ -0,0 +1,114 @@
+# Bot Management Configuration
+
+## Product Tiers
+
+### 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
+
+## 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
+```
+
+Categories: Search Engine Crawler, AI Crawler, Monitoring & Analytics, Aggregator, Security Intelligence, Academic Research
+
+## 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

package/dist/template/.opencode/skill/cloudflare/references/bot-management/gotchas.md

@@ -0,0 +1,99 @@
+# Bot Management Gotchas
+
+## Bot Score = 0
+
+**Cause**: Bot Management didn't run  
+**Reasons**: Internal Cloudflare request, Worker routing to zone (Orange-to-Orange), Request handled before BM (Redirect Rules, etc.)  
+**Solution**: Check request flow, ensure BM runs in request lifecycle
+
+## JavaScript Detections Not Working
+
+**Issue**: `js_detection.passed` always false or undefined  
+**Causes**:
+1. CSP headers don't allow `/cdn-cgi/challenge-platform/`
+2. Using on first page visit (needs HTML page first)
+3. Ad blockers or disabled JS
+4. JSD not enabled in dashboard
+5. Using Block action (must use Managed Challenge)
+
+**CSP Fix**:
+```txt
+Content-Security-Policy: script-src 'self' /cdn-cgi/challenge-platform/;
+```
+
+## False Positives
+
+**Issue**: Legitimate users blocked  
+**Solutions**:
+1. Check Bot Analytics for affected IPs/paths
+2. Identify detection source (ML, Heuristics, etc.)
+3. Create exception rule:
+```txt
+(cf.bot_management.score lt 30 and http.request.uri.path eq "/problematic-path")
+Action: Skip (Bot Management)
+```
+4. Or allowlist by IP/ASN/country
+
+## False Negatives (Bots Not Caught)
+
+**Issue**: Bots bypassing detection  
+**Solutions**:
+1. Lower score threshold (30 → 50)
+2. Enable JavaScript Detections
+3. Add JA3/JA4 fingerprinting rules
+4. Use rate limiting as fallback
+
+## Verified Bot Blocked
+
+**Issue**: Search engine bot blocked  
+**Causes**: WAF Managed Rules (not just Bot Management), Yandex bot during IP update (48h)  
+**Solution**: Create WAF exception for specific rule ID, verify bot via reverse DNS
+
+## JA3/JA4 Missing
+
+**Issue**: `ja3Hash` or `ja4` is undefined  
+**Causes**: Non-HTTPS traffic, Worker routing traffic, Orange-to-Orange traffic via Worker, Bot Management skipped  
+**Solution**: Only available for HTTPS/TLS traffic; check request routing
+
+## Bot Score Limitations
+
+- Score = 0 means **not computed** (not score = 100)
+- First request may not have JSD data
+- Score doesn't guarantee 100% accuracy
+- False positives/negatives possible
+
+## JavaScript Detections Limitations
+
+- Doesn't work on first HTML page visit
+- Requires JavaScript-enabled browser
+- Strips ETags from HTML responses
+- Not compatible with some CSP configurations
+- Not supported via `<meta>` CSP tags
+- Websocket endpoints not supported
+- Native mobile apps won't pass
+
+## JA3/JA4 Fingerprint Limitations
+
+- Only available for HTTPS/TLS traffic
+- Missing for Worker-routed traffic
+- Not unique per user (shared by clients with same browser/library)
+- Can change with browser/library updates
+
+## Plan Restrictions
+
+| Feature | Free | Pro/Business | Enterprise |
+|---------|------|--------------|------------|
+| Granular scores (1-99) | No | No | Yes |
+| JA3/JA4 | No | No | Yes |
+| Anomaly Detection | No | No | Yes |
+| Corporate Proxy detection | No | No | Yes |
+| Verified bot categories | Limited | Limited | Full |
+| Custom WAF rules | 5 | 20/100 | 1,000+ |
+
+## Technical Constraints
+
+- Max 25 WAF custom rules on Free (varies by plan)
+- Workers CPU time limits apply to bot logic
+- Bot Analytics sampling (1-10%)
+- 30-day maximum history
+- CSP requirements for JSD (must allow `/cdn-cgi/challenge-platform/`)

package/dist/template/.opencode/skill/cloudflare/references/bot-management/patterns.md

@@ -0,0 +1,125 @@
+# Bot Management Patterns
+
+## E-commerce Protection
+
+```txt
+# High security for checkout
+(cf.bot_management.score lt 50 and http.request.uri.path in {"/checkout" "/cart/add"} and not cf.bot_management.verified_bot and not cf.bot_management.corporate_proxy)
+Action: Managed Challenge
+```
+
+## API Protection
+
+```txt
+# Protect API with JS detection + score
+(http.request.uri.path matches "^/api/" and (cf.bot_management.score lt 30 or not cf.bot_management.js_detection.passed) and not cf.bot_management.verified_bot)
+Action: Block
+```
+
+## SEO-Friendly Bot Handling
+
+```txt
+# Allow search engine crawlers
+(cf.bot_management.score lt 30 and not cf.verified_bot_category in {"Search Engine Crawler"})
+Action: Managed Challenge
+```
+
+## Block AI Scrapers
+
+```txt
+# Block AI training bots
+(cf.verified_bot_category eq "AI Crawler")
+Action: Block
+
+# Or use dashboard: Security > Settings > Bot Management > Block AI Bots
+```
+
+## Rate Limiting by Bot Score
+
+```txt
+# Stricter limits for suspicious traffic
+(cf.bot_management.score lt 50)
+Rate: 10 requests per 10 seconds
+
+(cf.bot_management.score ge 50)
+Rate: 100 requests per 10 seconds
+```
+
+## Mobile App Allowlisting
+
+```txt
+# Identify mobile app by JA3/JA4
+(cf.bot_management.ja4 in {"fingerprint1" "fingerprint2"})
+Action: Skip (all remaining rules)
+```
+
+## Layered Defense
+
+```txt
+1. Bot Management (score-based)
+2. JavaScript Detections (for JS-capable clients)
+3. Rate Limiting (fallback protection)
+4. WAF Managed Rules (OWASP, etc.)
+```
+
+## Progressive Enhancement
+
+```txt
+Public content: High threshold (score < 10)
+Authenticated: Medium threshold (score < 30)
+Sensitive: Low threshold (score < 50) + JSD
+```
+
+## Zero Trust for Bots
+
+```txt
+1. Default deny (all scores < 30)
+2. Allowlist verified bots
+3. Allowlist mobile apps (JA3/JA4)
+4. Allowlist corporate proxies
+5. Allowlist static resources
+```
+
+## Workers: Score + JS Detection
+
+```typescript
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const cf = request.cf as any;
+    const botMgmt = cf?.botManagement;
+    const url = new URL(request.url);
+    
+    if (botMgmt?.staticResource) return fetch(request); // Skip static
+    
+    // API endpoints: require JS detection + good score
+    if (url.pathname.startsWith('/api/')) {
+      const jsDetectionPassed = botMgmt?.jsDetection?.passed ?? false;
+      const score = botMgmt?.score ?? 100;
+      
+      if (!jsDetectionPassed || score < 30) {
+        return new Response('Unauthorized', { status: 401 });
+      }
+    }
+    
+    return fetch(request);
+  }
+};
+```
+
+## Rate Limiting by JWT Claim + Bot Score
+
+```txt
+# Enterprise: Combine bot score with JWT validation
+Rate limiting > Custom rules
+- Field: lookup_json_string(http.request.jwt.claims["{config_id}"][0], "sub")
+- Matches: user ID claim
+- Additional condition: cf.bot_management.score lt 50
+```
+
+## WAF Integration Points
+
+- **WAF Custom Rules**: Primary enforcement mechanism
+- **Rate Limiting Rules**: Bot score as dimension, stricter limits for low scores
+- **Transform Rules**: Pass score to origin via custom header
+- **Workers**: Programmatic bot logic, custom scoring algorithms
+- **Page Rules / Configuration Rules**: Zone-level overrides, path-specific settings

package/dist/template/.opencode/skill/cloudflare/references/browser-rendering/README.md

@@ -0,0 +1,16 @@
+# Cloudflare Browser Rendering Skill Reference
+
+**Description**: Expert knowledge for Cloudflare Browser Rendering - control headless Chrome on Cloudflare's global network for browser automation, screenshots, PDFs, web scraping, testing, and content generation.
+
+**When to use**: Any task involving Cloudflare Browser Rendering including: taking sc...
+
+## In This Reference
+
+- **[configuration.md](./configuration.md)** - Setup, deployment, configuration
+- **[api.md](./api.md)** - API endpoints, methods, interfaces
+- **[patterns.md](./patterns.md)** - Common patterns, use cases, examples
+- **[gotchas.md](./gotchas.md)** - Troubleshooting, best practices, limitations
+
+## See Also
+
+- [Cloudflare Docs](https://developers.cloudflare.com/)

package/dist/template/.opencode/skill/cloudflare/references/browser-rendering/api.md

@@ -0,0 +1,54 @@
+## API Quick Reference
+
+### Puppeteer
+```typescript
+// Browser
+puppeteer.launch(env.MYBROWSER, opts?)
+puppeteer.connect(env.MYBROWSER, sessionId)
+puppeteer.sessions() // List open
+puppeteer.history()  // View closed
+puppeteer.limits()   // Check quotas
+
+browser.newPage()
+browser.close()
+browser.createIncognitoBrowserContext()
+
+// Page
+page.goto(url)
+page.content()
+page.screenshot()
+page.pdf()
+page.evaluate(fn)
+page.metrics()
+page.setUserAgent(ua)
+page.type(selector, text)
+page.click(selector)
+page.select(selector, value)
+```
+
+### Playwright
+```typescript
+// Browser
+launch(env.MYBROWSER, opts?)
+connect(env.MYBROWSER, sessionId)
+acquire(env.MYBROWSER) // Get new sessionId
+playwright.sessions()
+playwright.history()
+playwright.limits()
+
+browser.newPage()
+browser.newContext(opts?)
+browser.close()
+
+// Page
+page.goto(url)
+page.content()
+page.screenshot()
+page.getByTestId(id)
+page.getByPlaceholder(text)
+page.locator(selector)
+page.fill(selector, value)
+page.press(selector, key)
+
+// Context
+con

package/dist/template/.opencode/skill/cloudflare/references/browser-rendering/configuration.md

@@ -0,0 +1,47 @@
+### Wrangler Configuration
+```jsonc
+{
+  "name": "browser-worker",
+  "main": "src/index.js",
+  "compatibility_date": "2023-03-14",
+  "compatibility_flags": ["nodejs_compat"],
+  "browser": {
+    "binding": "MYBROWSER"
+  }
+}
+```
+
+### Basic Pattern
+```typescript
+import puppeteer from "@cloudflare/puppeteer";
+
+interface Env {
+  MYBROWSER: Fetcher;
+}
+
+export default {
+  async fetch(request, env): Promise<Response> {
+    const browser = await puppeteer.launch(env.MYBROWSER);
+    const page = await browser.newPage();
+    
+    try {
+      await page.goto("https://example.com");
+      const metrics = await page.metrics();
+      return Response.json(metrics);
+    } finally {
+      await browser.close(); // ALWAYS close in finally block
+    }
+  },
+} satisfies ExportedHandler<Env>;
+```
+
+### Keep-Alive Sessions
+```javascript
+// Default: 60 seconds idle timeout
+// Max: 10 minutes (600000 ms)
+const browser = await puppeteer.launch(env.MYBROWSER, { 
+  keep_alive: 600000 
+});
+```
+
+### Session Reuse Patt

package/dist/template/.opencode/skill/cloudflare/references/browser-rendering/gotchas.md

@@ -0,0 +1,29 @@
+## Best Practices
+
+### Always Close Browsers
+```typescript
+// ❌ BAD - Session stays open until timeout
+const browser = await puppeteer.launch(env.MYBROWSER);
+const page = await browser.newPage();
+await page.goto("https://example.com");
+return new Response(await page.content());
+
+// ✅ GOOD - Always use try/finally
+const browser = await puppeteer.launch(env.MYBROWSER);
+try {
+  const page = await browser.newPage();
+  await page.goto("https://example.com");
+  return new Response(await page.content());
+} finally {
+  await browser.close(); // Ensures cleanup even on errors
+}
+```
+
+### Optimize Concurrency
+Instead of launching multiple browsers:
+- Use multiple tabs in single browser
+- Reuse sessions with session IDs
+- Use incognito contexts for isolation without new browsers
+
+```typescript
+// ❌ BA

package/dist/template/.opencode/skill/cloudflare/references/browser-rendering/patterns.md

@@ -0,0 +1,29 @@
+## Integration Methods
+
+### 1. REST API
+**Best for**: Simple, stateless, one-off tasks
+
+**Authentication**: Requires API Token with `Browser Rendering - Edit` permissions
+
+**Base URL**: `https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/`
+
+**Available endpoints**:
+- `/content` - Fetch rendered HTML
+- `/screenshot` - Capture screenshots (PNG/JPEG)
+- `/pdf` - Generate PDFs
+- `/snapshot` - Webpage snapshots
+- `/scrape` - Extract HTML elements with selectors
+- `/json` - Extract structured data using AI
+- `/links` - Retrieve all links from page
+- `/markdown` - Convert page to markdown
+
+**Usage monitoring**: Response header `X-Browser-Ms-Used` reports browser time (milliseconds)
+
+**Example - Take screenshot**:
+```bash
+curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
+  -H 'Authorization: Bearer <apiToken>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "url": "https://example.com",
+    "screenshotOptions":