pi-cloudflare 0.1.0

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

@@ -0,0 +1,225 @@
+# Gotchas & Troubleshooting
+
+## Rate Limits & 429 Errors
+
+**Actual Limits:**
+- **1200 requests / 5 minutes** per user/token (global)
+- **200 requests / second** per IP address
+- **GraphQL: 320 / 5 minutes** (cost-based)
+
+**SDK Behavior:**
+- Auto-retry with exponential backoff (default 2 retries, Go: 10)
+- Respects `Retry-After` header
+- Throws `RateLimitError` after exhausting retries
+
+**Solution:**
+
+```typescript
+// Increase retries for rate-limit-heavy workflows
+const client = new Cloudflare({ maxRetries: 5 });
+
+// Add application-level throttling
+import pLimit from 'p-limit';
+const limit = pLimit(10); // Max 10 concurrent requests
+```
+
+## SDK-Specific Issues
+
+### Go: Required Field Wrapper
+
+**Problem:** Go SDK requires `cloudflare.F()` wrapper for optional fields.
+
+```go
+// ❌ WRONG - Won't compile or send field
+client.Zones.New(ctx, cloudflare.ZoneNewParams{
+    Name: "example.com",
+})
+
+// ✅ CORRECT
+client.Zones.New(ctx, cloudflare.ZoneNewParams{
+    Name: cloudflare.F("example.com"),
+    Account: cloudflare.F(cloudflare.ZoneNewParamsAccount{
+        ID: cloudflare.F("account-id"),
+    }),
+})
+```
+
+**Why:** Distinguishes between zero value, null, and omitted fields.
+
+### Python: Async vs Sync Clients
+
+**Problem:** Using sync client in async context or vice versa.
+
+```python
+# ❌ WRONG - Can't await sync client
+from cloudflare import Cloudflare
+client = Cloudflare()
+await client.zones.list()  # TypeError
+
+# ✅ CORRECT - Use AsyncCloudflare
+from cloudflare import AsyncCloudflare
+client = AsyncCloudflare()
+await client.zones.list()
+```
+
+## Token Permission Errors (403)
+
+**Problem:** API returns 403 Forbidden despite valid token.
+
+**Cause:** Token lacks required permissions (scope).
+
+**Scopes Required:**
+
+| Operation | Required Scope |
+|-----------|----------------|
+| List zones | Zone:Read (zone-level or account-level) |
+| Create zone | Zone:Edit (account-level) |
+| Edit DNS | DNS:Edit (zone-level) |
+| Deploy Worker | Workers Script:Edit (account-level) |
+| Read KV | Workers KV Storage:Read |
+| Write KV | Workers KV Storage:Edit |
+
+**Solution:** Re-create token with correct permissions in Dashboard → My Profile → API Tokens.
+
+## Pagination Truncation
+
+**Problem:** Only getting first 20 results (default page size).
+
+**Solution:** Use auto-pagination iterators.
+
+```typescript
+// ❌ WRONG - Only first page (20 items)
+const page = await client.zones.list();
+
+// ✅ CORRECT - All results
+const zones = [];
+for await (const zone of client.zones.list()) {
+  zones.push(zone);
+}
+```
+
+## Workers Subrequests
+
+**Problem:** Rate limit hit faster than expected in Workers.
+
+**Cause:** Workers subrequests count as separate API calls.
+
+**Solution:** Use bindings instead of REST API in Workers (see ../bindings/).
+
+```typescript
+// ❌ WRONG - REST API in Workers (counts against rate limit)
+const client = new Cloudflare({ apiToken: env.CLOUDFLARE_API_TOKEN });
+const zones = await client.zones.list();
+
+// ✅ CORRECT - Use bindings (no rate limit)
+// Access via env.MY_BINDING
+```
+
+## Authentication Errors (401)
+
+**Problem:** "Authentication failed" or "Invalid token"
+
+**Causes:**
+- Token expired
+- Token deleted/revoked
+- Token not set in environment
+- Wrong token format
+
+**Solution:**
+
+```typescript
+// Verify token is set
+if (!process.env.CLOUDFLARE_API_TOKEN) {
+  throw new Error('CLOUDFLARE_API_TOKEN not set');
+}
+
+// Test token
+const user = await client.user.tokens.verify();
+console.log('Token valid:', user.status);
+```
+
+## Timeout Errors
+
+**Problem:** Request times out (default 60s).
+
+**Cause:** Large operations (bulk DNS, zone transfers).
+
+**Solution:** Increase timeout or split operations.
+
+```typescript
+// Increase timeout
+const client = new Cloudflare({
+  timeout: 300000, // 5 minutes
+});
+
+// Or split operations
+const batchSize = 100;
+for (let i = 0; i < records.length; i += batchSize) {
+  const batch = records.slice(i, i + batchSize);
+  await processBatch(batch);
+}
+```
+
+## Zone Not Found (404)
+
+**Problem:** Zone ID valid but returns 404.
+
+**Causes:**
+- Zone not in account associated with token
+- Zone deleted
+- Wrong zone ID format
+
+**Solution:**
+
+```typescript
+// List all zones to find correct ID
+for await (const zone of client.zones.list()) {
+  console.log(zone.id, zone.name);
+}
+```
+
+## Limits Reference
+
+| Resource/Limit | Value | Notes |
+|----------------|-------|-------|
+| API rate limit | 1200/5min | Per user/token |
+| IP rate limit | 200/sec | Per IP |
+| GraphQL rate limit | 320/5min | Cost-based |
+| Parallel requests (recommended) | < 10 | Avoid overwhelming API |
+| Default page size | 20 | Use auto-pagination |
+| Max page size | 50 | Some endpoints |
+
+## Best Practices
+
+**Security:**
+- Never commit tokens
+- Use minimal permissions
+- Rotate tokens regularly
+- Set token expiration
+
+**Performance:**
+- Batch operations
+- Use pagination wisely
+- Cache responses
+- Handle rate limits
+
+**Code Organization:**
+
+```typescript
+// Create reusable client instance
+export const cfClient = new Cloudflare({
+  apiToken: process.env.CLOUDFLARE_API_TOKEN,
+  maxRetries: 5,
+});
+
+// Wrap common operations
+export async function getZoneDetails(zoneId: string) {
+  return await cfClient.zones.get({ zone_id: zoneId });
+}
+```
+
+## See Also
+
+- [api.md](./api.md) - Error types, authentication
+- [configuration.md](./configuration.md) - Timeout/retry configuration
+- [patterns.md](./patterns.md) - Error handling patterns

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

@@ -0,0 +1,204 @@
+# 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,141 @@
+# 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/)