# Cloudflare Portal Integration

## API Token Setup

The portal uses Cloudflare's v4 API for DNS management and (optionally) domain registration.

### Minimum token: DNS Edit Only

| Permission | Level | Why |
|---|---|---|
| Zone → DNS → Edit | All zones | View and manage DNS records |
| Account → Account Settings → Read | All accounts | List zones, verify token |
| TTL | Never expire | No unexpected lockouts |

### Extended token: Add Registrar access

To view domain expiry dates and purchase/transfer domains:

| Additional Permission | Level | Why |
|---|---|---|
| Account → Domain Registration → Read | All accounts | View expiry, auto-renew status |
| Account → Domain Registration → Edit | All accounts | Register new domains, toggle auto-renew |

### Turnstile (public form protection)

Turnstile is a separate widget key, NOT an API token. Generate at `dash.cloudflare.com → Turnstile → Add Widget`.

## Portal Pages

### DNS Zones page
- Lists all zones with status, plan, record count
- Links zones to portal customers by domain match
- Record editor: view/edit/delete DNS records by type, name, content, TTL, proxy status

### Registered Domains tab
- Shows all domains registered through Cloudflare Registrar
- Columns: domain, expiry date, auto-renew status, days left, linked customer
- Color coding: green (90+ days), amber (<90 days), red (<30 days or expired)
- Actions: Renew Now, Details, Register New Domain, Transfer Domain

## API Usage

```bash
# Verify token
curl -s https://api.cloudflare.com/client/v4/user/tokens/verify

# List zones
curl -s https://api.cloudflare.com/client/v4/zones -H "Authorization: Bearer $TOKEN"

# List DNS records for a zone
curl -s "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records" -H "Authorization: Bearer $TOKEN"

# List registered domains (needs registrar permission)
curl -s "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/registrar/domains" -H "Authorization: Bearer $TOKEN"
```

## Token Security

- Store in `~/.hermes/.env` as `CLOUDFLARE_API_TOKEN=cfut_...`
- Add to Wasabi backup scope (it's in .env which is in the live sync)
- If registrar token is created as a separate token, store as `CLOUDFLARE_REGISTRAR_TOKEN=`
- Turnstile site key and secret key stored in `.env` as `TURNSTILE_SITE_KEY` and `TURNSTILE_SECRET_KEY`