opencodekit 0.15.4 → 0.15.5

package/dist/template/.opencode/skill/cloudflare/references/tunnel/README.md

@@ -0,0 +1,82 @@
+# Cloudflare Tunnel
+
+Secure outbound-only connections between infrastructure and Cloudflare's global network.
+
+## Overview
+
+Cloudflare Tunnel (formerly Argo Tunnel) enables:
+- **Outbound-only connections** - No inbound ports or firewall changes
+- **Public hostname routing** - Expose local services to internet
+- **Private network access** - Connect internal networks via WARP
+- **Zero Trust integration** - Built-in access policies
+
+**Architecture**: Tunnel (persistent object) → Connector (`cloudflared` process) → Origin services
+
+## Quick Start
+
+```bash
+# Install cloudflared
+brew install cloudflared  # macOS
+
+# Authenticate
+cloudflared tunnel login
+
+# Create tunnel
+cloudflared tunnel create my-tunnel
+
+# Route DNS
+cloudflared tunnel route dns my-tunnel app.example.com
+
+# Run tunnel
+cloudflared tunnel run my-tunnel
+```
+
+## Core Commands
+
+```bash
+# Tunnel lifecycle
+cloudflared tunnel create <name>
+cloudflared tunnel list
+cloudflared tunnel info <name>
+cloudflared tunnel delete <name>
+
+# DNS routing
+cloudflared tunnel route dns <tunnel> <hostname>
+cloudflared tunnel route list
+
+# Private network
+cloudflared tunnel route ip add 10.0.0.0/8 <tunnel>
+
+# Run tunnel
+cloudflared tunnel run <name>
+```
+
+## Configuration Example
+
+```yaml
+# ~/.cloudflared/config.yml
+tunnel: 6ff42ae2-765d-4adf-8112-31c55c1551ef
+credentials-file: /root/.cloudflared/6ff42ae2-765d-4adf-8112-31c55c1551ef.json
+
+ingress:
+  - hostname: app.example.com
+    service: http://localhost:8000
+  - hostname: api.example.com
+    service: https://localhost:8443
+    originRequest:
+      noTLSVerify: true
+  - service: http_status:404
+```
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - Config file options, ingress rules, TLS settings
+- [api.md](./api.md) - Cloudflare API, remotely-managed tunnels, programmatic control
+- [patterns.md](./patterns.md) - Docker, Kubernetes, HA, service types, use cases
+- [gotchas.md](./gotchas.md) - Troubleshooting, limitations, best practices
+
+## See Also
+
+- [workers](../workers/) - Workers with Tunnel integration
+- [access](../access/) - Zero Trust access policies
+- [warp](../warp/) - WARP client for private networks

package/dist/template/.opencode/skill/cloudflare/references/tunnel/api.md

@@ -0,0 +1,105 @@
+# Tunnel API
+
+## Cloudflare API Access
+
+**Base URL**: `https://api.cloudflare.com/client/v4`
+
+**Authentication**:
+```bash
+Authorization: Bearer ${CF_API_TOKEN}
+```
+
+## Create Tunnel
+
+```bash
+curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels" \
+  -H "Authorization: Bearer ${CF_API_TOKEN}" \
+  -H "Content-Type: application/json" \
+  --data '{
+    "name": "my-tunnel",
+    "tunnel_secret": "<base64-secret>"
+  }'
+```
+
+## List Tunnels
+
+```bash
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels" \
+  -H "Authorization: Bearer ${CF_API_TOKEN}"
+```
+
+## Get Tunnel Info
+
+```bash
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}" \
+  -H "Authorization: Bearer ${CF_API_TOKEN}"
+```
+
+## Update Tunnel Config
+
+```bash
+curl -X PUT "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}/configurations" \
+  -H "Authorization: Bearer ${CF_API_TOKEN}" \
+  -H "Content-Type: application/json" \
+  --data '{
+    "config": {
+      "ingress": [
+        {"hostname": "app.example.com", "service": "http://localhost:8000"},
+        {"service": "http_status:404"}
+      ]
+    }
+  }'
+```
+
+## Delete Tunnel
+
+```bash
+curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}" \
+  -H "Authorization: Bearer ${CF_API_TOKEN}"
+```
+
+## Remotely-Managed Tunnels
+
+### Via Dashboard
+1. **Zero Trust** > **Networks** > **Tunnels**
+2. **Create a tunnel** > **Cloudflared**
+3. Copy install command with token
+4. Run on origin:
+```bash
+cloudflared service install <TOKEN>
+```
+
+### Via Token
+```bash
+# Run with token (no config file needed)
+cloudflared tunnel --no-autoupdate run --token ${TUNNEL_TOKEN}
+
+# Docker
+docker run cloudflare/cloudflared:latest tunnel --no-autoupdate run --token ${TUNNEL_TOKEN}
+```
+
+## DNS Routes API
+
+```bash
+# Create DNS route
+curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}/connections" \
+  -H "Authorization: Bearer ${CF_API_TOKEN}" \
+  --data '{"hostname": "app.example.com"}'
+
+# Delete route
+curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}/connections/{route_id}" \
+  -H "Authorization: Bearer ${CF_API_TOKEN}"
+```
+
+## Private Network Routes API
+
+```bash
+# Add IP route
+curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}/routes" \
+  -H "Authorization: Bearer ${CF_API_TOKEN}" \
+  --data '{"ip_network": "10.0.0.0/8"}'
+
+# List IP routes
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}/routes" \
+  -H "Authorization: Bearer ${CF_API_TOKEN}"
+```

package/dist/template/.opencode/skill/cloudflare/references/tunnel/configuration.md

@@ -0,0 +1,113 @@
+# Tunnel Configuration
+
+## Config File Location
+
+```
+~/.cloudflared/config.yml          # User config
+/etc/cloudflared/config.yml        # System-wide (Linux)
+```
+
+## Basic Structure
+
+```yaml
+tunnel: <UUID>
+credentials-file: /path/to/<UUID>.json
+
+ingress:
+  - hostname: app.example.com
+    service: http://localhost:8000
+  - service: http_status:404  # Required catch-all
+```
+
+## Ingress Rules
+
+Rules evaluated **top to bottom**, first match wins.
+
+```yaml
+ingress:
+  # Exact hostname + path regex
+  - hostname: static.example.com
+    path: \.(jpg|png|css|js)$
+    service: https://localhost:8001
+  
+  # Wildcard hostname
+  - hostname: "*.example.com"
+    service: https://localhost:8002
+  
+  # Path only (all hostnames)
+  - path: /api/.*
+    service: http://localhost:9000
+  
+  # Catch-all (required)
+  - service: http_status:404
+```
+
+**Validation**:
+```bash
+cloudflared tunnel ingress validate
+cloudflared tunnel ingress rule https://foo.example.com
+```
+
+## Service Types
+
+| Protocol | Format | Client Requirement |
+|----------|--------|-------------------|
+| HTTP | `http://localhost:8000` | Browser |
+| HTTPS | `https://localhost:8443` | Browser |
+| TCP | `tcp://localhost:2222` | `cloudflared access tcp` |
+| SSH | `ssh://localhost:22` | `cloudflared access ssh` |
+| RDP | `rdp://localhost:3389` | `cloudflared access rdp` |
+| Unix | `unix:/path/to/socket` | Browser |
+| Test | `hello_world` | Browser |
+
+## Origin Configuration
+
+### Connection Settings
+```yaml
+originRequest:
+  connectTimeout: 30s
+  tlsTimeout: 10s
+  tcpKeepAlive: 30s
+  keepAliveTimeout: 90s
+  keepAliveConnections: 100
+```
+
+### TLS Settings
+```yaml
+originRequest:
+  noTLSVerify: true                      # Disable cert verification
+  originServerName: "app.internal"       # Override SNI
+  caPool: /path/to/ca.pem                # Custom CA
+```
+
+### HTTP Settings
+```yaml
+originRequest:
+  disableChunkedEncoding: true
+  httpHostHeader: "app.internal"
+  http2Origin: true
+```
+
+## Private Network Mode
+
+```yaml
+tunnel: <UUID>
+credentials-file: /path/to/creds.json
+
+warp-routing:
+  enabled: true
+```
+
+```bash
+cloudflared tunnel route ip add 10.0.0.0/8 my-tunnel
+cloudflared tunnel route ip add 192.168.1.100/32 my-tunnel
+```
+
+## Environment Variables
+
+```bash
+TUNNEL_TOKEN=<token>                    # Remotely-managed token
+TUNNEL_ORIGIN_CERT=/path/to/cert.pem   # Override cert path
+NO_AUTOUPDATE=true                      # Disable auto-updates
+TUNNEL_LOGLEVEL=debug                   # Log level
+```

package/dist/template/.opencode/skill/cloudflare/references/tunnel/gotchas.md

@@ -0,0 +1,115 @@
+# Tunnel Gotchas
+
+## Common Issues
+
+### Error 1016 (Origin DNS Error)
+
+**Cause**: Tunnel not running or not connected
+
+**Fix**:
+```bash
+cloudflared tunnel info my-tunnel     # Check status
+ps aux | grep cloudflared             # Verify running
+journalctl -u cloudflared -n 100      # Check logs
+```
+
+### Certificate Errors
+
+**Issue**: Self-signed certs rejected
+
+**Fix**:
+```yaml
+originRequest:
+  noTLSVerify: true      # Dev only
+  caPool: /path/to/ca.pem  # Custom CA
+```
+
+### Connection Timeouts
+
+**Issue**: Origin slow to respond
+
+**Fix**:
+```yaml
+originRequest:
+  connectTimeout: 60s
+  tlsTimeout: 20s
+  keepAliveTimeout: 120s
+```
+
+### Tunnel Not Starting
+
+**Check**:
+```bash
+cloudflared tunnel ingress validate  # Validate config
+ls -la ~/.cloudflared/*.json         # Verify credentials
+cloudflared tunnel list              # Verify tunnel exists
+```
+
+## Best Practices
+
+### Security
+1. Use remotely-managed tunnels for centralized control
+2. Enable Access policies for sensitive services
+3. Rotate tunnel credentials regularly
+4. Verify TLS certs (`noTLSVerify: false`)
+5. Restrict `bastion` service type
+
+### Performance
+1. Run multiple replicas for HA
+2. Place `cloudflared` close to origin (same network)
+3. Use HTTP/2 for gRPC (`http2Origin: true`)
+4. Tune keepalive for long-lived connections
+5. Monitor connection counts
+
+### Configuration
+1. Use environment variables for secrets
+2. Version control config files
+3. Validate before deploying (`cloudflared tunnel ingress validate`)
+4. Test rules (`cloudflared tunnel ingress rule <URL>`)
+5. Document rule order (first match wins)
+
+### Operations
+1. Monitor tunnel health in dashboard
+2. Set up disconnect alerts
+3. Graceful shutdown for config updates
+4. Keep `cloudflared` updated (1 year support)
+5. Use `--no-autoupdate` in prod; control updates manually
+
+## Limitations
+
+- **Free tier**: Unlimited tunnels and traffic
+- **Tunnel limit**: 1000 replicas per tunnel
+- **Connection duration**: No hard limit (hours to days)
+- **Long-lived connections**: Drop during replica updates (WebSocket, SSH, UDP)
+
+## Debug Mode
+
+```bash
+cloudflared tunnel --loglevel debug run my-tunnel
+cloudflared tunnel ingress rule https://app.example.com
+```
+
+## Migration Strategies
+
+### From Ngrok
+```yaml
+# Ngrok: ngrok http 8000
+# Cloudflare Tunnel:
+ingress:
+  - hostname: app.example.com
+    service: http://localhost:8000
+  - service: http_status:404
+```
+
+### From VPN
+```yaml
+# Replace VPN with private network routing
+warp-routing:
+  enabled: true
+```
+
+```bash
+cloudflared tunnel route ip add 10.0.0.0/8 my-tunnel
+```
+
+Users install WARP client instead of VPN.

package/dist/template/.opencode/skill/cloudflare/references/tunnel/patterns.md

@@ -0,0 +1,157 @@
+# Tunnel Patterns
+
+## Docker Deployment
+
+### Quick Tunnel
+```dockerfile
+FROM cloudflare/cloudflared:latest
+CMD ["tunnel", "--url", "http://app:8080"]
+```
+
+### Named Tunnel
+```yaml
+services:
+  cloudflared:
+    image: cloudflare/cloudflared:latest
+    command: tunnel --no-autoupdate run --token ${TUNNEL_TOKEN}
+    restart: unless-stopped
+  app:
+    image: myapp:latest
+```
+
+### With Config File
+```yaml
+services:
+  cloudflared:
+    image: cloudflare/cloudflared:latest
+    volumes:
+      - ./config.yml:/etc/cloudflared/config.yml:ro
+      - ./credentials.json:/etc/cloudflared/credentials.json:ro
+    command: tunnel --config /etc/cloudflared/config.yml run
+```
+
+## Kubernetes Deployment
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: cloudflared
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: cloudflared
+  template:
+    metadata:
+      labels:
+        app: cloudflared
+    spec:
+      containers:
+      - name: cloudflared
+        image: cloudflare/cloudflared:latest
+        args:
+        - tunnel
+        - --no-autoupdate
+        - run
+        - --token
+        - $(TUNNEL_TOKEN)
+        env:
+        - name: TUNNEL_TOKEN
+          valueFrom:
+            secretKeyRef:
+              name: tunnel-credentials
+              key: token
+```
+
+## High Availability
+
+```yaml
+# Same config on multiple servers
+tunnel: <UUID>
+credentials-file: /path/to/creds.json
+
+ingress:
+  - hostname: app.example.com
+    service: http://localhost:8000
+  - service: http_status:404
+```
+
+Run on multiple machines:
+```bash
+# Server 1
+cloudflared tunnel run my-tunnel
+
+# Server 2 (same config)
+cloudflared tunnel run my-tunnel
+```
+
+Cloudflare automatically load balances. Long-lived connections (WebSocket, SSH) will drop during updates.
+
+## Use Cases
+
+### Web Application
+```yaml
+ingress:
+  - hostname: myapp.example.com
+    service: http://localhost:3000
+  - service: http_status:404
+```
+
+### SSH Access
+```yaml
+ingress:
+  - hostname: ssh.example.com
+    service: ssh://localhost:22
+  - service: http_status:404
+```
+
+Client:
+```bash
+cloudflared access ssh --hostname ssh.example.com
+```
+
+### gRPC Service
+```yaml
+ingress:
+  - hostname: grpc.example.com
+    service: http://localhost:50051
+    originRequest:
+      http2Origin: true
+  - service: http_status:404
+```
+
+### Multiple Environments
+```yaml
+ingress:
+  - hostname: prod.example.com
+    service: http://localhost:8001
+  - hostname: staging.example.com
+    service: http://localhost:8002
+  - hostname: dev.example.com
+    service: http://localhost:8003
+  - service: http_status:404
+```
+
+## Service Installation
+
+### Linux systemd
+```bash
+cloudflared service install
+systemctl start cloudflared
+systemctl enable cloudflared
+systemctl status cloudflared
+
+# Logs
+journalctl -u cloudflared -f
+```
+
+### macOS launchd
+```bash
+sudo cloudflared service install
+sudo launchctl start com.cloudflare.cloudflared
+sudo launchctl load -w /Library/LaunchDaemons/com.cloudflare.cloudflared.plist
+
+# Logs
+tail -f /Library/Logs/com.cloudflare.cloudflared.err.log
+```