memory-journal-mcp 7.7.1 → 8.0.0

package/skills/cloudflare/references/api-shield/gotchas.md

@@ -0,0 +1,132 @@
+# Gotchas & Troubleshooting
+
+## Common Errors
+
+### "Schema Validation 2.0 not working after migration"
+
+**Cause:** Classic rules still active, conflicting with new system
+**Solution:**
+
+1. Delete ALL Classic schema validation rules
+2. Clear Cloudflare cache (wait 5 min)
+3. Re-upload schema via new Schema Validation 2.0 interface
+4. Verify in Security > Events
+5. Check action is set (Log/Block)
+
+### "Schema validation blocking valid requests"
+
+**Cause:** Schema too restrictive, missing fields, or incorrect types
+**Solution:**
+
+1. Check Firewall Events for violation details
+2. Review schema in Settings
+3. Test schema in Swagger Editor
+4. Use Log mode to validate before blocking
+5. Update schema with correct specifications
+6. Ensure Schema Validation 2.0 (not Classic)
+
+### "JWT validation failing"
+
+**Cause:** JWKS mismatch with IdP, expired token, wrong header/cookie name, or clock skew
+**Solution:**
+
+1. Verify JWKS matches IdP configuration
+2. Check token `exp` claim is valid
+3. Confirm header/cookie name matches config
+4. Test token at jwt.io
+5. Account for clock skew (±5 min tolerance)
+6. Use modern syntax: `is_jwt_valid(http.request.jwt.payload["{config_id}"][0])`
+
+### "BOLA detection false positives"
+
+**Cause:** Legitimate sequential access patterns, bulk operations, or sensitivity too high
+**Solution:**
+
+1. Review BOLA events in Security > Events
+2. Lower sensitivity threshold (High → Medium → Low)
+3. Exclude legitimate bulk operations from detection
+4. Ensure session identifiers uniquely identify users
+5. Verify minimum traffic requirements met (1000+ req/day)
+
+### "Risk labels not appearing in firewall rules"
+
+**Cause:** Feature not enabled, insufficient traffic, or missing session identifiers
+**Solution:**
+
+1. Verify Schema Validation 2.0 enabled
+2. Enable BOLA Detection in schema settings
+3. Configure session identifiers (required for BOLA)
+4. Wait 24-48h for ML model training
+5. Check minimum traffic thresholds met
+
+### "Endpoint discovery not finding APIs"
+
+**Cause:** Insufficient traffic (<500 reqs/10d), non-2xx responses, Worker direct requests, or incorrect session ID config
+**Solution:** Ensure 500+ requests in 10 days, 2xx responses from edge (not Workers direct), configure session IDs correctly. ML updates daily.
+
+### "Sequence detection false positives"
+
+**Cause:** Lookback window issues, non-unique session IDs, or model sensitivity
+**Solution:**
+
+1. Review lookback settings (10 reqs to managed endpoints, 10min window)
+2. Ensure session ID uniqueness per user (not shared tokens)
+3. Adjust positive/negative model balance
+4. Exclude legitimate workflows from detection
+
+### "GraphQL protection blocking valid queries"
+
+**Cause:** Query depth/size limits too restrictive, complex but legitimate queries
+**Solution:**
+
+1. Review blocked query patterns in Security > Events
+2. Increase max_depth (default: 10) if needed
+3. Increase max_size (default: 100KB) for complex queries
+4. Whitelist specific query signatures
+5. Use Log mode to tune before blocking
+
+### "Token invalid"
+
+**Cause:** Configuration error, JWKS mismatch, or expired token
+**Solution:** Verify config matches IdP, update JWKS, check token expiration
+
+### "Schema violation"
+
+**Cause:** Missing required fields, wrong data types, or spec mismatch
+**Solution:** Review schema against actual requests, ensure all required fields present, validate types match spec
+
+### "Fallthrough"
+
+**Cause:** Unknown endpoint or pattern mismatch
+**Solution:** Update schema with all endpoints, check path pattern matching
+
+### "mTLS failed"
+
+**Cause:** Certificate untrusted/expired or wrong CA
+**Solution:** Verify cert chain, check expiration, confirm correct CA uploaded
+
+## Limits (2026)
+
+| Resource/Limit            | Value                   | Notes                              |
+| ------------------------- | ----------------------- | ---------------------------------- |
+| OpenAPI version           | v3.0.x only             | No external refs, must be valid    |
+| Schema operations         | 10K (Enterprise)        | Contact for higher limits          |
+| JWT validation sources    | Headers/cookies only    | No query params/body               |
+| Endpoint discovery        | 500+ reqs/10d           | Minimum for ML model               |
+| Path normalization        | Automatic               | `/profile/238` → `/profile/{var1}` |
+| Schema parameters         | No `content` field      | No object param validation         |
+| BOLA detection            | 1000+ reqs/day/endpoint | Per-endpoint minimum               |
+| Session ID uniqueness     | Required                | BOLA/Sequence need unique IDs      |
+| GraphQL max depth         | 1-50                    | Default: 10                        |
+| GraphQL max size          | 1KB-1MB                 | Default: 100KB                     |
+| JWT claim nesting         | 10 levels max           | Use dot notation                   |
+| mTLS CA certificates      | 5 custom max            | CF-managed unlimited               |
+| Schema upload size        | 5MB max                 | Compressed OpenAPI spec            |
+| Volumetric abuse baseline | 7 days training         | Initial ML period                  |
+| Auth Posture refresh      | Daily                   | Updated nightly                    |
+
+## See Also
+
+- [configuration.md](configuration.md) - Setup guides to avoid common issues
+- [patterns.md](patterns.md) - Best practices and progressive rollout
+- [API Shield Docs](https://developers.cloudflare.com/api-shield/)

package/skills/cloudflare/references/api-shield/patterns.md

@@ -0,0 +1,185 @@
+# Patterns & Use Cases
+
+## Protect API with Schema + JWT
+
+```bash
+# 1. Upload OpenAPI schema
+POST /zones/{zone_id}/api_gateway/user_schemas
+
+# 2. Configure JWT validation
+POST /zones/{zone_id}/api_gateway/token_validation
+{
+  "name": "Auth0",
+  "location": {"header": "Authorization"},
+  "jwks": "{...}"
+}
+
+# 3. Create JWT rule
+POST /zones/{zone_id}/api_gateway/jwt_validation_rules
+
+# 4. Set schema validation action
+PUT /zones/{zone_id}/api_gateway/settings/schema_validation
+{"validation_default_mitigation_action": "block"}
+```
+
+## Progressive Rollout
+
+```
+1. Log mode: Observe false positives
+   - Schema: Action = Log
+   - JWT: Action = Log
+
+2. Block subset: Protect critical endpoints
+   - Change specific endpoint actions to Block
+   - Monitor firewall events
+
+3. Full enforcement: Block all violations
+   - Change default action to Block
+   - Handle fallthrough with custom rule
+```
+
+## BOLA Detection
+
+### Enumeration Detection
+
+Detects sequential resource access (e.g., `/users/1`, `/users/2`, `/users/3`).
+
+```javascript
+// Block BOLA enumeration attempts
+(cf.api_gateway.cf-risk-bola-enumeration and http.host eq "api.example.com")
+// Action: Block or Challenge
+```
+
+### Parameter Pollution
+
+Detects duplicate/excessive parameters in requests.
+
+```javascript
+// Block parameter pollution
+(cf.api_gateway.cf-risk-bola-pollution and http.host eq "api.example.com")
+// Action: Block
+```
+
+### Combined BOLA Protection
+
+```javascript
+// Comprehensive BOLA rule
+(cf.api_gateway.cf-risk-bola-enumeration or cf.api_gateway.cf-risk-bola-pollution)
+and http.host eq "api.example.com"
+// Action: Block
+```
+
+## Authentication Posture
+
+### Detect Missing Auth
+
+```javascript
+// Log endpoints lacking authentication
+(cf.api_gateway.cf-risk-missing-auth and http.host eq "api.example.com")
+// Action: Log (for audit)
+```
+
+### Detect Mixed Auth
+
+```javascript
+// Alert on inconsistent auth patterns
+(cf.api_gateway.cf-risk-mixed-auth and http.host eq "api.example.com")
+// Action: Log (review required)
+```
+
+## Fallthrough Detection (Shadow APIs)
+
+```javascript
+// WAF Custom Rule
+(cf.api_gateway.fallthrough_triggered and http.host eq "api.example.com")
+// Action: Log (discover unknown) or Block (strict)
+```
+
+## Rate Limiting by User
+
+```javascript
+// Rate Limiting Rule (modern syntax)
+(http.host eq "api.example.com" and
+ is_jwt_valid(http.request.jwt.payload["{config_id}"][0]))
+
+// Rate: 100 req/60s
+// Counting expression: lookup_json_string(http.request.jwt.payload["{config_id}"][0], "sub")
+```
+
+## Volumetric Abuse Response
+
+```javascript
+// Detect abnormal traffic spikes
+(cf.api_gateway.volumetric_abuse_detected and http.host eq "api.example.com")
+// Action: Challenge or Rate Limit
+
+// Combined with rate limiting
+(cf.api_gateway.volumetric_abuse_detected or
+ cf.threat_score gt 50) and http.host eq "api.example.com"
+// Action: JS Challenge
+```
+
+## GraphQL Protection
+
+```javascript
+// Block oversized queries
+(http.request.uri.path eq "/graphql" and
+ cf.api_gateway.graphql_query_size gt 100000)
+// Action: Block
+
+// Block deep nested queries
+(http.request.uri.path eq "/graphql" and
+ cf.api_gateway.graphql_query_depth gt 10)
+// Action: Block
+```
+
+## Architecture Patterns
+
+**Public API:** Discovery + Schema Validation 2.0 + JWT + Rate Limiting + Bot Management  
+**Partner API:** mTLS + Schema Validation + Sequence Mitigation  
+**Internal API:** Discovery + Schema Learning + Auth Posture
+
+## OWASP API Security Top 10 Mapping (2026)
+
+| OWASP Issue                                 | API Shield Solutions                                                                          |
+| ------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| API1:2023 Broken Object Level Authorization | **BOLA Detection** (enumeration + pollution), Sequence mitigation, Schema, JWT, Rate Limiting |
+| API2:2023 Broken Authentication             | **Auth Posture**, mTLS, JWT validation, Bot Management                                        |
+| API3:2023 Broken Object Property Auth       | Schema validation, JWT validation                                                             |
+| API4:2023 Unrestricted Resource Access      | Rate Limiting, **Volumetric Abuse Detection**, **GraphQL Protection**, Bot Management         |
+| API5:2023 Broken Function Level Auth        | Schema validation, JWT validation, Auth Posture                                               |
+| API6:2023 Unrestricted Business Flows       | Sequence mitigation, Bot Management                                                           |
+| API7:2023 SSRF                              | Schema validation, WAF managed rules                                                          |
+| API8:2023 Security Misconfiguration         | **Schema Validation 2.0**, Auth Posture, WAF rules                                            |
+| API9:2023 Improper Inventory Management     | **API Discovery**, Schema learning, Auth Posture                                              |
+| API10:2023 Unsafe API Consumption           | JWT validation, Schema validation, WAF managed                                                |
+
+## Monitoring
+
+**Security Events:** `Security > Events` → Filter: Action = block, Service = API Shield  
+**Firewall Analytics:** `Analytics > Security` → Filter by `cf.api_gateway.*` fields  
+**Logpush fields:** APIGatewayAuthIDPresent, APIGatewayRequestViolatesSchema, APIGatewayFallthroughDetected, JWTValidationResult
+
+## Availability (2026)
+
+| Feature                    | Availability      | Notes                |
+| -------------------------- | ----------------- | -------------------- |
+| mTLS (CF-managed CA)       | All plans         | Self-service         |
+| Endpoint Management        | All plans         | Limited operations   |
+| Schema Validation 2.0      | All plans         | Limited operations   |
+| API Discovery              | Enterprise        | 10K+ ops             |
+| JWT Validation             | Enterprise add-on | Full validation      |
+| BOLA Detection             | Enterprise add-on | Requires session IDs |
+| Auth Posture               | Enterprise add-on | Security audit       |
+| Volumetric Abuse Detection | Enterprise add-on | Traffic analysis     |
+| GraphQL Protection         | Enterprise add-on | Query limits         |
+| Sequence Mitigation        | Enterprise (beta) | Contact team         |
+| Full Suite                 | Enterprise add-on | All features         |
+
+**Enterprise limits:** 10K operations (contact for higher). Preview access available for non-contract evaluation.
+
+## See Also
+
+- [configuration.md](configuration.md) - Setup all features before creating rules
+- [api.md](api.md) - Firewall field reference and API endpoints
+- [gotchas.md](gotchas.md) - Common issues and limits

package/skills/cloudflare/references/argo-smart-routing/README.md

@@ -0,0 +1,96 @@
+# Cloudflare Argo Smart Routing Skill Reference
+
+## Overview
+
+Cloudflare Argo Smart Routing is a performance optimization service that detects real-time network issues and routes web traffic across the most efficient network path. It continuously monitors network conditions and intelligently routes traffic through the fastest, most reliable routes in Cloudflare's network.
+
+**Note on Smart Shield:** Argo Smart Routing is being integrated into Cloudflare's Smart Shield product for enhanced DDoS protection and performance. Existing Argo customers maintain full functionality with gradual migration to Smart Shield features.
+
+## Quick Start
+
+### Enable via cURL
+
+```bash
+curl -X PATCH "https://api.cloudflare.com/client/v4/zones/{zone_id}/argo/smart_routing" \
+  -H "Authorization: Bearer YOUR_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"value": "on"}'
+```
+
+### Enable via TypeScript SDK
+
+```typescript
+import Cloudflare from 'cloudflare'
+
+const client = new Cloudflare({ apiToken: process.env.CLOUDFLARE_API_TOKEN })
+
+const result = await client.argo.smartRouting.edit({
+  zone_id: 'your-zone-id',
+  value: 'on',
+})
+
+console.log(`Argo enabled: ${result.value}`)
+```
+
+## Core Concepts
+
+### What It Does
+
+- **Intelligent routing**: Detects congestion, outages, packet loss in real-time
+- **Global optimization**: Routes across 300+ Cloudflare data centers
+- **Automatic failover**: Switches paths when issues detected (typically <1s)
+- **Works with existing setup**: No origin changes required
+
+### Billing Model
+
+- Usage-based: Charged per GB of traffic (excluding DDoS/WAF mitigated traffic)
+- Requires billing configuration before enabling
+- Available on Enterprise+ plans (check zone eligibility)
+
+### When to Use
+
+- **High-traffic production sites** with global user base
+- **Latency-sensitive applications** (APIs, real-time services)
+- **Sites behind Cloudflare proxy** (orange-clouded DNS records)
+- **Combined with Tiered Cache** for maximum performance gains
+
+### When NOT to Use
+
+- Development/staging environments (cost control)
+- Low-traffic sites (<1TB/month) where cost may exceed benefit
+- Sites with primarily single-region traffic
+
+## Should I Enable Argo?
+
+| Your Situation                            | Recommendation                      |
+| ----------------------------------------- | ----------------------------------- |
+| Global production app, >1TB/month traffic | ✅ Enable - likely ROI positive     |
+| Enterprise plan, latency-critical APIs    | ✅ Enable - performance matters     |
+| Regional site, <100GB/month traffic       | ⚠️ Evaluate - cost may not justify  |
+| Development/staging environment           | ❌ Disable - use in production only |
+| Not yet configured billing                | ❌ Configure billing first          |
+
+## Reading Order by Task
+
+| Your Goal                     | Start With                                               | Then Read                  |
+| ----------------------------- | -------------------------------------------------------- | -------------------------- |
+| Enable Argo for first time    | Quick Start above → [configuration.md](configuration.md) | [gotchas.md](gotchas.md)   |
+| Use TypeScript/Python SDK     | [api.md](api.md)                                         | [patterns.md](patterns.md) |
+| Terraform/IaC setup           | [configuration.md](configuration.md)                     | -                          |
+| Enable for Spectrum TCP app   | [patterns.md](patterns.md) → Spectrum section            | [api.md](api.md)           |
+| Troubleshoot enablement issue | [gotchas.md](gotchas.md)                                 | [api.md](api.md)           |
+| Manage billing/usage          | [patterns.md](patterns.md) → Billing section             | [gotchas.md](gotchas.md)   |
+
+## In This Reference
+
+- **[api.md](api.md)** - API endpoints, SDK methods, error handling, Python/TypeScript examples
+- **[configuration.md](configuration.md)** - Terraform setup, environment config, billing configuration
+- **[patterns.md](patterns.md)** - Tiered Cache integration, Spectrum TCP apps, billing management, validation patterns
+- **[gotchas.md](gotchas.md)** - Common errors, permission issues, limits, best practices
+
+## See Also
+
+- [Cloudflare Argo Smart Routing Docs](https://developers.cloudflare.com/argo-smart-routing/)
+- [Cloudflare Smart Shield](https://developers.cloudflare.com/smart-shield/)
+- [Spectrum Documentation](https://developers.cloudflare.com/spectrum/)
+- [Tiered Cache](https://developers.cloudflare.com/cache/how-to/tiered-cache/)

package/skills/cloudflare/references/argo-smart-routing/api.md

@@ -0,0 +1,253 @@
+## API Reference
+
+**Note on Smart Shield:** Argo Smart Routing is being integrated into Cloudflare's Smart Shield product. API endpoints remain stable; existing integrations continue to work without changes.
+
+### Base Endpoint
+
+```
+https://api.cloudflare.com/client/v4
+```
+
+### Authentication
+
+Use API tokens with Zone:Argo Smart Routing:Edit permissions:
+
+```bash
+# Headers required
+X-Auth-Email: user@example.com
+Authorization: Bearer YOUR_API_TOKEN
+```
+
+### Get Argo Smart Routing Status
+
+**Endpoint:** `GET /zones/{zone_id}/argo/smart_routing`
+
+**Description:** Retrieves current Argo Smart Routing enablement status.
+
+**cURL Example:**
+
+```bash
+curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/argo/smart_routing" \
+  -H "Authorization: Bearer YOUR_API_TOKEN" \
+  -H "Content-Type: application/json"
+```
+
+**Response:**
+
+```json
+{
+  "result": {
+    "id": "smart_routing",
+    "value": "on",
+    "editable": true,
+    "modified_on": "2024-01-11T12:00:00Z"
+  },
+  "success": true,
+  "errors": [],
+  "messages": []
+}
+```
+
+**TypeScript SDK Example:**
+
+```typescript
+import Cloudflare from 'cloudflare'
+
+const client = new Cloudflare({
+  apiToken: process.env.CLOUDFLARE_API_TOKEN,
+})
+
+const status = await client.argo.smartRouting.get({ zone_id: 'your-zone-id' })
+console.log(`Argo status: ${status.value}, editable: ${status.editable}`)
+```
+
+**Python SDK Example:**
+
+```python
+from cloudflare import Cloudflare
+
+client = Cloudflare(api_token=os.environ.get('CLOUDFLARE_API_TOKEN'))
+
+status = client.argo.smart_routing.get(zone_id='your-zone-id')
+print(f"Argo status: {status.value}, editable: {status.editable}")
+```
+
+### Update Argo Smart Routing Status
+
+**Endpoint:** `PATCH /zones/{zone_id}/argo/smart_routing`
+
+**Description:** Enable or disable Argo Smart Routing for a zone.
+
+**Request Body:**
+
+```json
+{
+  "value": "on" // or "off"
+}
+```
+
+**cURL Example:**
+
+```bash
+curl -X PATCH "https://api.cloudflare.com/client/v4/zones/{zone_id}/argo/smart_routing" \
+  -H "Authorization: Bearer YOUR_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"value": "on"}'
+```
+
+**TypeScript SDK Example:**
+
+```typescript
+const result = await client.argo.smartRouting.edit({
+  zone_id: 'your-zone-id',
+  value: 'on',
+})
+console.log(`Updated: ${result.value} at ${result.modified_on}`)
+```
+
+**Python SDK Example:**
+
+```python
+result = client.argo.smart_routing.edit(
+    zone_id='your-zone-id',
+    value='on'
+)
+print(f"Updated: {result.value} at {result.modified_on}")
+```
+
+## Checking Editability Before Updates
+
+**Critical:** Always check the `editable` field before attempting to enable/disable Argo. When `editable: false`, the zone has restrictions (billing not configured, insufficient permissions, or plan limitations).
+
+**Pattern:**
+
+```typescript
+async function safelyEnableArgo(client: Cloudflare, zoneId: string): Promise<boolean> {
+  const status = await client.argo.smartRouting.get({ zone_id: zoneId })
+
+  if (!status.editable) {
+    console.error('Cannot modify Argo: editable=false (check billing/permissions)')
+    return false
+  }
+
+  if (status.value === 'on') {
+    console.log('Argo already enabled')
+    return true
+  }
+
+  await client.argo.smartRouting.edit({ zone_id: zoneId, value: 'on' })
+  console.log('Argo enabled successfully')
+  return true
+}
+```
+
+**Python Pattern:**
+
+```python
+def safely_enable_argo(client: Cloudflare, zone_id: str) -> bool:
+    status = client.argo.smart_routing.get(zone_id=zone_id)
+
+    if not status.editable:
+        print('Cannot modify Argo: editable=false (check billing/permissions)')
+        return False
+
+    if status.value == 'on':
+        print('Argo already enabled')
+        return True
+
+    client.argo.smart_routing.edit(zone_id=zone_id, value='on')
+    print('Argo enabled successfully')
+    return True
+```
+
+## Error Handling
+
+The TypeScript SDK provides typed error classes for robust error handling:
+
+```typescript
+import Cloudflare from 'cloudflare'
+import { APIError, APIConnectionError, RateLimitError } from 'cloudflare'
+
+async function enableArgoWithErrorHandling(client: Cloudflare, zoneId: string) {
+  try {
+    const result = await client.argo.smartRouting.edit({
+      zone_id: zoneId,
+      value: 'on',
+    })
+    return result
+  } catch (error) {
+    if (error instanceof RateLimitError) {
+      console.error('Rate limited. Retry after:', error.response?.headers.get('retry-after'))
+      // Implement exponential backoff
+    } else if (error instanceof APIError) {
+      console.error('API error:', error.status, error.message)
+      if (error.status === 403) {
+        console.error('Permission denied - check API token scopes')
+      } else if (error.status === 400) {
+        console.error('Bad request - verify zone_id and payload')
+      }
+    } else if (error instanceof APIConnectionError) {
+      console.error('Connection failed:', error.message)
+      // Retry with exponential backoff
+    } else {
+      console.error('Unexpected error:', error)
+    }
+    throw error
+  }
+}
+```
+
+**Python Error Handling:**
+
+```python
+from cloudflare import Cloudflare, APIError, RateLimitError
+
+def enable_argo_with_error_handling(client: Cloudflare, zone_id: str):
+    try:
+        result = client.argo.smart_routing.edit(zone_id=zone_id, value='on')
+        return result
+    except RateLimitError as e:
+        print(f"Rate limited. Retry after: {e.response.headers.get('retry-after')}")
+        raise
+    except APIError as e:
+        print(f"API error: {e.status} - {e.message}")
+        if e.status == 403:
+            print('Permission denied - check API token scopes')
+        elif e.status == 400:
+            print('Bad request - verify zone_id and payload')
+        raise
+    except Exception as e:
+        print(f"Unexpected error: {e}")
+        raise
+```
+
+## Response Schema
+
+All Argo Smart Routing API responses follow this structure:
+
+```typescript
+interface ArgoSmartRoutingResponse {
+  result: {
+    id: 'smart_routing'
+    value: 'on' | 'off'
+    editable: boolean
+    modified_on: string // ISO 8601 timestamp
+  }
+  success: boolean
+  errors: Array<{
+    code: number
+    message: string
+  }>
+  messages: Array<string>
+}
+```
+
+## Key Response Fields
+
+| Field         | Type            | Description                                      |
+| ------------- | --------------- | ------------------------------------------------ |
+| `value`       | `"on" \| "off"` | Current enablement status                        |
+| `editable`    | `boolean`       | Whether changes are allowed (check before PATCH) |
+| `modified_on` | `string`        | ISO timestamp of last modification               |
+| `success`     | `boolean`       | Whether request succeeded                        |
+| `errors`      | `Array`         | Error details if `success: false`                |