---
name: cloudflare-tunnel-manager
description: >
  Plan/apply/rollback for Cloudflare Tunnel lifecycle (create, configure,
  route DNS, run as service). Includes DRY_RUN safety gates, status matrix,
  and audit report. Triggers: 'cloudflare tunnel', 'create tunnel', 'tunnel plan',
  'tunnel rollback', 'cloudflared config', 'dns route'.
version: 1.0.0
---

# Cloudflare Tunnel Manager

Tier 1 skill for managing **Cloudflare Tunnels** safely:
- **Plan → Apply** workflow (two-phase)
- **Rollback** scripts for DNS route, service, and tunnel delete
- Verification + audit report

Designed for sovereign Node A style setups where you terminate TLS at Cloudflare
and route traffic to a local service over a tunnel.

## Quick Start

```bash
cd ~/.claude/skills/cloudflare-tunnel-manager

# Required
export CF_API_TOKEN="..."           # Cloudflare API token
export CF_ACCOUNT_ID="..."          # Cloudflare account ID

# Tunnel identity
export TUNNEL_NAME="node-a-tunnel"
export ZONE_NAME="example.com"      # domain in Cloudflare
export HOSTNAME="node-a.example.com"

# Local origin (what tunnel forwards to)
export LOCAL_SERVICE="http://127.0.0.1:9110"

# Safety
export DRY_RUN=1
export REQUIRE_CONFIRM=1
export CONFIRM_PHRASE="I UNDERSTAND THIS CAN CHANGE DNS AND TUNNEL ROUTES"

./scripts/00_preflight.sh
./scripts/10_tunnel_plan.sh
./scripts/20_dns_plan.sh
./scripts/30_service_plan.sh

export DRY_RUN=0
./scripts/11_tunnel_apply.sh
./scripts/21_dns_apply.sh
./scripts/31_service_apply.sh

./scripts/90_verify.sh
./scripts/99_report.sh
```

## Inputs

| Parameter | Required | Default | Description |
|---|---:|---|---|
| CF_API_TOKEN | Yes | (none) | Cloudflare API token with Tunnel + DNS permissions |
| CF_ACCOUNT_ID | Yes | (none) | Cloudflare account ID |
| TUNNEL_NAME | Yes | (none) | Tunnel name |
| ZONE_NAME | Yes | (none) | Zone/domain in Cloudflare (e.g., example.com) |
| HOSTNAME | Yes | (none) | DNS hostname to route (e.g., node-a.example.com) |
| LOCAL_SERVICE | Yes | (none) | Local origin URL (e.g., http://127.0.0.1:9110) |
| CONFIG_DIR | No | outputs/config | Where generated config lives |
| SERVICE_NAME | No | cloudflared-tunnel | systemd unit name |
| DRY_RUN | No | 1 | Apply scripts refuse unless DRY_RUN=0 |
| REQUIRE_CONFIRM | No | 1 | Require confirmation phrase |
| CONFIRM_PHRASE | No | I UNDERSTAND THIS CAN CHANGE DNS AND TUNNEL ROUTES | Safety phrase |

## Outputs

- `outputs/config/config.yml` (generated cloudflared config)
- `outputs/config/tunnel.json` (tunnel metadata snapshot)
- `outputs/status_matrix.json`
- `outputs/audit_report.md`

## Safety Guarantees

1. Default **DRY_RUN=1**
2. Confirmation phrase required for apply and rollback
3. Plan scripts print exact commands and expected changes
4. Rollbacks available:
   - DNS route removal
   - systemd service stop/disable
   - tunnel delete (optional)

## Notes

- This skill uses `cloudflared` CLI.
- You can run the tunnel without systemd (manual) if desired.

## EU Compliance

| Aspect | Value |
|---|---|
| Data Residency | EU (Ireland - Dublin) |
| Jurisdiction | Irish Law |
| Transport | Encrypted tunnel (Cloudflare) |
| Logs | Local status + reports only |

## References
- [Cloudflare Tunnel Notes](references/cloudflare_tunnel_notes.md)