---
name: dns-sovereign
description: >
  PowerDNS + Cloudflare hybrid DNS with plan/apply/rollback, audit trail,
  and verification. Deploys a sovereign PowerDNS authoritative server
  (Docker) and optionally syncs selected records to Cloudflare.
  Triggers: 'dns sovereign', 'powerdns', 'authoritative dns', 'dns plan',
  'dns rollback', 'sync dns to cloudflare'.
version: 1.0.0
---

# DNS Sovereign (PowerDNS + Cloudflare Hybrid)

This skill establishes **Node B** (or dedicated DNS node) as your sovereign
authoritative DNS, with Cloudflare as an optional edge mirror / public resolver layer.

## What v1.0.0 Does

**PowerDNS Authoritative (Docker)**
- Deploys PowerDNS authoritative server using sqlite backend
- Enables the PowerDNS API
- Creates a first zone (optional) via API
- Produces an audit report + status matrix

**Optional Cloudflare Sync**
- Push a limited set of records (A/AAAA/CNAME/TXT) to Cloudflare using API token
- Designed as a *mirror*, not source of truth

## Quick Start

```bash
cd ~/.claude/skills/dns-sovereign

# PowerDNS (required)
export MODE="docker"
export PDNS_PORT=53
export PDNS_WEB_PORT=8081
export PDNS_API_KEY="..."            # choose a strong random token
export PDNS_DATA_DIR="$HOME/pdns"

# Zone (optional but recommended)
export ZONE_NAME="example.com"       # authoritative zone name (must end with . in PDNS API ops)
export NS1_NAME="ns1.example.com"
export NS2_NAME="ns2.example.com"

# Cloudflare mirror (optional)
export CF_API_TOKEN=""               # if set, sync scripts can run
export CF_ZONE_NAME="example.com"    # Cloudflare zone to mirror into

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

./scripts/00_preflight.sh
./scripts/10_pdns_plan.sh

export DRY_RUN=0
./scripts/11_pdns_apply.sh

# Optional: create zone + NS records in PDNS
./scripts/20_zone_plan.sh
export DRY_RUN=0
./scripts/21_zone_apply.sh

# Optional: mirror records to Cloudflare (does not pull)
./scripts/30_cf_plan.sh
export DRY_RUN=0
./scripts/31_cf_apply.sh

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

## Inputs

| Parameter | Required | Default | Description |
|---|---:|---|---|
| MODE | Yes | docker | docker |
| PDNS_API_KEY | Yes | (none) | PowerDNS API key |
| PDNS_DATA_DIR | No | ~/pdns | Persistent storage |
| PDNS_PORT | No | 53 | DNS port |
| PDNS_WEB_PORT | No | 8081 | API/Web port |
| ZONE_NAME | No | (empty) | Zone to create (e.g., example.com) |
| NS1_NAME | No | ns1.<zone> | Primary NS hostname |
| NS2_NAME | No | ns2.<zone> | Secondary NS hostname |
| CF_API_TOKEN | No | (empty) | Cloudflare API token (for mirroring) |
| CF_ZONE_NAME | No | (empty) | Cloudflare zone name |
| DRY_RUN | No | 1 | Apply refuses unless DRY_RUN=0 |
| REQUIRE_CONFIRM | No | 1 | Require confirmation phrase |
| CONFIRM_PHRASE | No | I UNDERSTAND THIS CAN CHANGE DNS | Safety phrase |

## Outputs

- `outputs/compose.yml`
- `outputs/pdns.conf`
- `outputs/pdns_api_probe.json`
- `outputs/status_matrix.json`
- `outputs/audit_report.md`
- `outputs/backups/<timestamp>/...`

## Safety Guarantees

1. Default **DRY_RUN=1**
2. Confirmation phrase required
3. Backups for compose + config
4. Rollback scripts:
   - stop/remove PDNS container (data preserved)
   - delete zone (optional)
   - remove mirrored Cloudflare records created by this skill (best-effort)

## EU Compliance

| Aspect | Value |
|---|---|
| Data Residency | EU (Ireland - Dublin) |
| Jurisdiction | Irish Law |
| Authoritative Source | PowerDNS on your node |
| Mirror | Optional Cloudflare mirror |

## References
- [PowerDNS Notes](references/powerdns_notes.md)
- [Cloudflare DNS Mirror Notes](references/cloudflare_dns_mirror_notes.md)