memory-journal-mcp 7.7.0 → 8.0.0

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

@@ -0,0 +1,208 @@
+# Common Patterns
+
+## List All with Auto-Pagination
+
+**Problem:** API returns paginated results. Default page size is 20.
+
+**Solution:** Use SDK auto-pagination to iterate all results.
+
+```typescript
+// TypeScript
+for await (const zone of client.zones.list()) {
+  console.log(zone.name)
+}
+```
+
+```python
+# Python
+for zone in client.zones.list():
+    print(zone.name)
+```
+
+```go
+// Go
+iter := client.Zones.ListAutoPaging(ctx, cloudflare.ZoneListParams{})
+for iter.Next() {
+    fmt.Println(iter.Current().Name)
+}
+```
+
+## Error Handling with Retry
+
+**Problem:** Rate limits (429) and transient errors need retry.
+
+**Solution:** SDKs auto-retry with exponential backoff. Customize as needed.
+
+```typescript
+// Increase retries for rate-limit-heavy operations
+const client = new Cloudflare({ maxRetries: 5 })
+
+try {
+  const zone = await client.zones.create({
+    /* ... */
+  })
+} catch (err) {
+  if (err instanceof Cloudflare.RateLimitError) {
+    // Already retried 5 times with backoff
+    const retryAfter = err.headers['retry-after']
+    console.log(`Rate limited. Retry after ${retryAfter}s`)
+  }
+}
+```
+
+## Batch Parallel Operations
+
+**Problem:** Need to create multiple resources quickly.
+
+**Solution:** Use `Promise.all()` for parallel requests (respect rate limits).
+
+```typescript
+// Create multiple DNS records in parallel
+const records = ['www', 'api', 'cdn'].map((subdomain) =>
+  client.dns.records.create({
+    zone_id: 'zone-id',
+    type: 'A',
+    name: `${subdomain}.example.com`,
+    content: '192.0.2.1',
+  })
+)
+await Promise.all(records)
+```
+
+**Controlled concurrency** (avoid rate limits):
+
+```typescript
+import pLimit from 'p-limit'
+const limit = pLimit(10) // Max 10 concurrent
+
+const subdomains = ['www', 'api', 'cdn' /* many more */]
+const records = subdomains.map((subdomain) =>
+  limit(() =>
+    client.dns.records.create({
+      zone_id: 'zone-id',
+      type: 'A',
+      name: `${subdomain}.example.com`,
+      content: '192.0.2.1',
+    })
+  )
+)
+await Promise.all(records)
+```
+
+## Zone CRUD Workflow
+
+```typescript
+// Create
+const zone = await client.zones.create({
+  account: { id: 'account-id' },
+  name: 'example.com',
+  type: 'full',
+})
+
+// Read
+const fetched = await client.zones.get({ zone_id: zone.id })
+
+// Update
+await client.zones.edit(zone.id, { paused: false })
+
+// Delete
+await client.zones.delete(zone.id)
+```
+
+## DNS Bulk Update
+
+```typescript
+// Fetch all A records
+const records = []
+for await (const record of client.dns.records.list({
+  zone_id: 'zone-id',
+  type: 'A',
+})) {
+  records.push(record)
+}
+
+// Update all to new IP
+await Promise.all(
+  records.map((record) =>
+    client.dns.records.update({
+      zone_id: 'zone-id',
+      dns_record_id: record.id,
+      type: 'A',
+      name: record.name,
+      content: '203.0.113.1', // New IP
+      proxied: record.proxied,
+      ttl: record.ttl,
+    })
+  )
+)
+```
+
+## Filter and Collect Results
+
+```typescript
+// Find all proxied A records
+const proxiedRecords = []
+for await (const record of client.dns.records.list({
+  zone_id: 'zone-id',
+  type: 'A',
+})) {
+  if (record.proxied) {
+    proxiedRecords.push(record)
+  }
+}
+```
+
+## Error Recovery Pattern
+
+```typescript
+async function createZoneWithRetry(name: string, maxAttempts = 3) {
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await client.zones.create({
+        account: { id: 'account-id' },
+        name,
+        type: 'full',
+      })
+    } catch (err) {
+      if (err instanceof Cloudflare.RateLimitError && attempt < maxAttempts) {
+        const retryAfter = parseInt(err.headers['retry-after'] || '5')
+        console.log(`Rate limited, waiting ${retryAfter}s (retry ${attempt}/${maxAttempts})`)
+        await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000))
+      } else {
+        throw err
+      }
+    }
+  }
+}
+```
+
+## Conditional Update Pattern
+
+```typescript
+// Only update if zone is active
+const zone = await client.zones.get({ zone_id: 'zone-id' })
+if (zone.status === 'active') {
+  await client.zones.edit(zone.id, { paused: false })
+}
+```
+
+## Batch with Error Handling
+
+```typescript
+// Process multiple zones, continue on errors
+const results = await Promise.allSettled(zoneIds.map((id) => client.zones.get({ zone_id: id })))
+
+results.forEach((result, i) => {
+  if (result.status === 'fulfilled') {
+    console.log(`Zone ${i}: ${result.value.name}`)
+  } else {
+    console.error(`Zone ${i} failed:`, result.reason.message)
+  }
+})
+```
+
+## See Also
+
+- [api.md](./api.md) - SDK client initialization, basic operations
+- [gotchas.md](./gotchas.md) - Rate limits, common errors
+- [configuration.md](./configuration.md) - SDK configuration options

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

@@ -0,0 +1,44 @@
+# Cloudflare API Shield Reference
+
+Expert guidance for API Shield - comprehensive API security suite for discovery, protection, and monitoring.
+
+## Reading Order
+
+| Task                     | Files to Read                  |
+| ------------------------ | ------------------------------ |
+| Initial setup            | README → configuration.md      |
+| Implement JWT validation | configuration.md → api.md      |
+| Add schema validation    | configuration.md → patterns.md |
+| Detect API attacks       | patterns.md → api.md           |
+| Debug issues             | gotchas.md                     |
+
+## Feature Selection
+
+What protection do you need?
+
+```
+├─ Validate request/response structure → Schema Validation 2.0 (configuration.md)
+├─ Verify auth tokens → JWT Validation (configuration.md)
+├─ Client certificates → mTLS (configuration.md)
+├─ Detect BOLA attacks → BOLA Detection (patterns.md)
+├─ Track auth coverage → Auth Posture (patterns.md)
+├─ Stop volumetric abuse → Abuse Detection (patterns.md)
+└─ Discover shadow APIs → API Discovery (api.md)
+```
+
+## In This Reference
+
+- **[configuration.md](configuration.md)** - Setup, session identifiers, rules, token/mTLS configs
+- **[api.md](api.md)** - Endpoint management, discovery, validation APIs, GraphQL operations
+- **[patterns.md](patterns.md)** - Common patterns, progressive rollout, OWASP mappings, workflows
+- **[gotchas.md](gotchas.md)** - Troubleshooting, false positives, performance, best practices
+
+## Quick Start
+
+API Shield: Enterprise-grade API security (Discovery, Schema Validation 2.0, JWT, mTLS, BOLA Detection, Auth Posture). Available as Enterprise add-on with preview access.
+
+## See Also
+
+- [API Shield Docs](https://developers.cloudflare.com/api-shield/)
+- [API Reference](https://developers.cloudflare.com/api/resources/api_gateway/)
+- [OWASP API Security Top 10](https://owasp.org/www-project-api-security/)

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

@@ -0,0 +1,153 @@
+# API Reference
+
+Base: `/zones/{zone_id}/api_gateway`
+
+## Endpoints
+
+```bash
+GET /operations                    # List
+GET /operations/{op_id}            # Get single
+POST /operations/item              # Create: {endpoint,host,method}
+POST /operations                   # Bulk: {operations:[{endpoint,host,method}]}
+DELETE /operations/{op_id}         # Delete
+DELETE /operations                 # Bulk delete: {operation_ids:[...]}
+```
+
+## Discovery
+
+```bash
+GET /discovery/operations                    # List discovered
+PATCH /discovery/operations/{op_id}          # Update: {state:"saved"|"ignored"}
+PATCH /discovery/operations                  # Bulk: {operation_ids:{id:{state}}}
+GET /discovery                               # OpenAPI export
+```
+
+## Config
+
+```bash
+GET /configuration        # Get session ID config
+PUT /configuration        # Update: {auth_id_characteristics:[{name,type:"header"|"cookie"}]}
+```
+
+## Token Validation
+
+```bash
+GET /token_validation                  # List
+POST /token_validation                 # Create: {name,location:{header:"..."},jwks:"..."}
+POST /jwt_validation_rules             # Rule: {name,hostname,token_validation_id,action:"block"}
+```
+
+## Workers Integration
+
+### Access JWT Claims
+
+```js
+export default {
+  async fetch(req, env) {
+    // Access validated JWT payload
+    const jwt = req.cf?.jwt?.payload?.[env.JWT_CONFIG_ID]?.[0]
+    if (jwt) {
+      const userId = jwt.sub
+      const role = jwt.role
+    }
+  },
+}
+```
+
+### Access mTLS Info
+
+```js
+export default {
+  async fetch(req, env) {
+    const tls = req.cf?.tlsClientAuth
+    if (tls?.certVerified === 'SUCCESS') {
+      const fingerprint = tls.certFingerprintSHA256
+      // Authenticated client
+    }
+  },
+}
+```
+
+### Dynamic JWKS Update
+
+```js
+export default {
+  async scheduled(event, env) {
+    const jwks = await (await fetch('https://auth.example.com/.well-known/jwks.json')).json()
+    await fetch(
+      `https://api.cloudflare.com/client/v4/zones/${env.ZONE_ID}/api_gateway/token_validation/${env.CONFIG_ID}`,
+      {
+        method: 'PATCH',
+        headers: {
+          Authorization: `Bearer ${env.CF_API_TOKEN}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ jwks: JSON.stringify(jwks) }),
+      }
+    )
+  },
+}
+```
+
+## Firewall Fields
+
+### Core Fields
+
+```js
+cf.api_gateway.auth_id_present // Session ID present
+cf.api_gateway.request_violates_schema // Schema violation
+cf.api_gateway.fallthrough_triggered // No endpoint match
+cf.tls_client_auth.cert_verified // mTLS cert valid
+cf.tls_client_auth.cert_fingerprint_sha256
+```
+
+### JWT Validation (2026)
+
+```js
+// Modern validation syntax
+is_jwt_valid(http.request.jwt.payload['{config_id}'][0])
+
+// Legacy (still supported)
+cf.api_gateway.jwt_claims_valid
+
+// Extract claims
+lookup_json_string(http.request.jwt.payload['{config_id}'][0], 'claim_name')
+```
+
+### Risk Labels (2026)
+
+```js
+// BOLA detection
+cf.api_gateway.cf - risk - bola - enumeration // Sequential resource access detected
+cf.api_gateway.cf - risk - bola - pollution // Parameter pollution detected
+
+// Authentication posture
+cf.api_gateway.cf - risk - missing - auth // Endpoint lacks authentication
+cf.api_gateway.cf - risk - mixed - auth // Inconsistent auth patterns
+```
+
+## BOLA Detection
+
+```bash
+GET /user_schemas/{schema_id}/bola             # Get BOLA config
+PATCH /user_schemas/{schema_id}/bola           # Update: {enabled:true}
+```
+
+## Auth Posture
+
+```bash
+GET /discovery/authentication_posture          # List unprotected endpoints
+```
+
+## GraphQL Protection
+
+```bash
+GET /settings/graphql_protection               # Get limits
+PUT /settings/graphql_protection               # Set: {max_depth,max_size}
+```
+
+## See Also
+
+- [configuration.md](configuration.md) - Setup guides for all features
+- [patterns.md](patterns.md) - Firewall rules and common patterns
+- [API Gateway API Docs](https://developers.cloudflare.com/api/resources/api_gateway/)

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

@@ -0,0 +1,210 @@
+# Configuration
+
+## Schema Validation 2.0 Setup
+
+> ⚠️ **Classic Schema Validation deprecated.** Use Schema Validation 2.0.
+
+**Upload schema (Dashboard):**
+
+```
+Security > API Shield > Schema Validation > Add validation
+- Upload .yml/.yaml/.json (OpenAPI v3.0)
+- Endpoints auto-added to Endpoint Management
+- Action: Log | Block | None
+- Body inspection: JSON payloads
+```
+
+**Change validation action:**
+
+```
+Security > API Shield > Settings > Schema Validation
+Per-endpoint: Filter → ellipses → Change action
+Default action: Set global mitigation action
+```
+
+**Migration from Classic:**
+
+```
+1. Export existing schema (if available)
+2. Delete all Classic schema validation rules
+3. Wait 5 min for cache clear
+4. Re-upload via Schema Validation 2.0 interface
+5. Verify in Security > Events
+```
+
+**Fallthrough rule** (catch-all unknown endpoints):
+
+```
+Security > API Shield > Settings > Fallthrough > Use Template
+- Select hostnames
+- Create rule with cf.api_gateway.fallthrough_triggered
+- Action: Log (discover) or Block (strict)
+```
+
+**Body inspection:** Supports `application/json`, `*/*`, `application/*`. Disable origin MIME sniffing to prevent bypasses.
+
+## JWT Validation
+
+**Setup token config:**
+
+```
+Security > API Shield > Settings > JWT Settings > Add configuration
+- Name: "Auth0 JWT Config"
+- Location: Header/Cookie + name (e.g., "Authorization")
+- JWKS: Paste public keys from IdP
+```
+
+**Create validation rule:**
+
+```
+Security > API Shield > API Rules > Add rule
+- Hostname: api.example.com
+- Deselect endpoints to ignore
+- Token config: Select config
+- Enforce presence: Ignore or Mark as non-compliant
+- Action: Log/Block/Challenge
+```
+
+**Rate limit by JWT claim:**
+
+```wirefilter
+lookup_json_string(http.request.jwt.claims["{config_id}"][0], "sub")
+```
+
+**Special cases:**
+
+- Two JWTs, different IdPs: Create 2 configs, select both, "Validate all"
+- IdP migration: 2 configs + 2 rules, adjust actions per state
+- Bearer prefix: API Shield handles with/without
+- Nested claims: Dot notation `user.email`
+
+## Mutual TLS (mTLS)
+
+**Setup:**
+
+```
+SSL/TLS > Client Certificates > Create Certificate
+- Generate CF-managed CA (all plans)
+- Upload custom CA (Enterprise, max 5)
+```
+
+**Configure mTLS rule:**
+
+```
+Security > API Shield > mTLS
+- Select hostname(s)
+- Choose certificate(s)
+- Action: Block/Log/Challenge
+```
+
+**Test:**
+
+```bash
+openssl req -x509 -newkey rsa:4096 -keyout client-key.pem -out client-cert.pem -days 365
+curl https://api.example.com/endpoint --cert client-cert.pem --key client-key.pem
+```
+
+## Session Identifiers
+
+Critical for BOLA Detection, Sequence Mitigation, and analytics. Configure header/cookie that uniquely IDs API users.
+
+**Examples:** JWT sub claim, session token, API key, custom user ID header
+
+**Configure:**
+
+```
+Security > API Shield > Settings > Session Identifiers
+- Type: Header/Cookie
+- Name: "X-User-ID" or "Authorization"
+```
+
+## BOLA Detection
+
+Detects Broken Object Level Authorization attacks (enumeration + parameter pollution).
+
+**Enable:**
+
+```
+Security > API Shield > Schema Validation > [Select Schema] > BOLA Detection
+- Enable detection
+- Threshold: Sensitivity level (Low/Medium/High)
+- Action: Log or Block
+```
+
+**Requirements:**
+
+- Schema Validation 2.0 enabled
+- Session identifiers configured
+- Minimum traffic: 1000+ requests/day per endpoint
+
+## Authentication Posture
+
+Identifies unprotected or inconsistently protected endpoints.
+
+**View report:**
+
+```
+Security > API Shield > Authentication Posture
+- Shows endpoints lacking JWT/mTLS
+- Highlights mixed authentication patterns
+```
+
+**Remediate:**
+
+1. Review flagged endpoints
+2. Add JWT validation rules
+3. Configure mTLS for sensitive endpoints
+4. Monitor posture score
+
+## Volumetric Abuse + GraphQL
+
+**Volumetric Abuse Detection:**
+`Security > API Shield > Settings > Volumetric Abuse Detection`
+
+- Enable per-endpoint monitoring, set thresholds, action: Log | Challenge | Block
+
+**GraphQL Protection:**
+`Security > API Shield > Settings > GraphQL Protection`
+
+- Max query depth: 10, max size: 100KB, block introspection (production)
+
+## Terraform
+
+```hcl
+# Session identifier
+resource "cloudflare_api_shield" "main" {
+  zone_id = var.zone_id
+  auth_id_characteristics {
+    type = "header"
+    name = "Authorization"
+  }
+}
+
+# Add endpoint
+resource "cloudflare_api_shield_operation" "users_get" {
+  zone_id  = var.zone_id
+  method   = "GET"
+  host     = "api.example.com"
+  endpoint = "/api/users/{id}"
+}
+
+# JWT validation rule
+resource "cloudflare_ruleset" "jwt_validation" {
+  zone_id = var.zone_id
+  name    = "API JWT Validation"
+  kind    = "zone"
+  phase   = "http_request_firewall_custom"
+
+  rules {
+    action = "block"
+    expression = "(http.host eq \"api.example.com\" and not is_jwt_valid(http.request.jwt.payload[\"{config_id}\"][0]))"
+    description = "Block invalid JWTs"
+  }
+}
+```
+
+## See Also
+
+- [api.md](api.md) - API endpoints and Workers integration
+- [patterns.md](patterns.md) - Firewall rules and deployment patterns
+- [gotchas.md](gotchas.md) - Troubleshooting and limits