dns-record-manager

## When to use this skill

Use this skill when working with dns-record-manager: adding or editing DNS records, reviewing the change audit log, configuring provider credentials, or deploying the stack.

## Quick Start (development)

```bash
cd dns-record-manager
pnpm install
cp .env.example .env
# Edit .env: add CLOUDFLARE_API_TOKEN and/or AWS credentials

cd backend && pnpm dev
# In a separate terminal:
cd frontend && pnpm dev
# Dashboard: http://localhost:5173
```

## Quick Start (Docker)

```bash
cp .env.example .env
# Edit .env with your provider credentials
docker compose up -d
# Dashboard: http://localhost:8080
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `3000` | Express server port |
| `DB_PATH` | `./data/dns.db` | SQLite audit log path |
| `CLOUDFLARE_API_TOKEN` | `` | Cloudflare API token (Zone:Read + DNS:Edit) |
| `CLOUDFLARE_ZONE_IDS` | `` | Comma-separated zone IDs (empty = all zones) |
| `AWS_ACCESS_KEY_ID` | `` | AWS access key for Route 53 |
| `AWS_SECRET_ACCESS_KEY` | `` | AWS secret key |
| `AWS_REGION` | `us-east-1` | AWS region |
| `ROUTE53_HOSTED_ZONE_IDS` | `` | Comma-separated hosted zone IDs (empty = all) |
| `STATIC_ZONES_FILE` | `` | Path to static JSON file (dev fallback) |
| `CORS_ORIGIN` | `http://localhost:5173` | Dashboard CORS origin |
| `VITE_API_URL` | `http://localhost:3000` | API base URL for frontend |

## API Reference

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/health` | `{ ok: true }` |
| `GET` | `/api/zones` | All zones across all providers |
| `GET` | `/api/zones/:zoneId/records` | Records for a zone |
| `POST` | `/api/zones/:zoneId/records` | Create a record |
| `PUT` | `/api/zones/:zoneId/records/:recordId` | Update a record |
| `DELETE` | `/api/zones/:zoneId/records/:recordId` | Delete a record |
| `GET` | `/api/audit` | Last 200 change log entries |
| `GET` | `/api/settings` | Current settings |
| `POST` | `/api/settings` | Update settings |

## Record Types

| Type | Color | Typical Use |
|------|-------|-------------|
| A | Blue | IPv4 address |
| AAAA | Indigo | IPv6 address |
| CNAME | Violet | Alias to another hostname |
| MX | Amber | Mail server (with priority) |
| TXT | Emerald | SPF, DKIM, DMARC, site verification |
| NS | Gray | Nameserver delegation |
| SRV | Pink | Service location |
| CAA | Red | CA authorization |

## Record Request Body

```json
{
  "name": "app.example.com",
  "type": "A",
  "content": "198.51.100.42",
  "ttl": 300,
  "proxied": true,
  "comment": "Production app server"
}
```

For MX records, include `"priority": 10`. For CNAME, `content` is the target hostname.

## Audit Log

Every create, update, and delete writes a row to `change_log` before and after the provider API call. The `old_value` and `new_value` columns contain JSON snapshots of the record.

View recent changes:

```bash
curl http://localhost:3000/api/audit
```

## Cloudflare API Token

Required permissions:
- Zone: Read (to list zones)
- DNS: Edit (to create/update/delete records)

Scope: "All zones" or a specific zone list.

## Route 53 IAM Policy

Minimum required permissions:

```json
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "route53:ListHostedZones",
      "route53:ListResourceRecordSets",
      "route53:ChangeResourceRecordSets"
    ],
    "Resource": "*"
  }]
}
```

## Static JSON File Format (Development)

```json
[
  {
    "id": "zone-1",
    "name": "dev.local",
    "records": [
      {
        "id": "rec-1",
        "name": "app.dev.local",
        "type": "A",
        "content": "127.0.0.1",
        "ttl": 300
      }
    ]
  }
]
```

## Troubleshooting

**"No zones found"**
- Verify at least one provider is configured (check Settings page)
- For Cloudflare: test the token with `curl -H "Authorization: Bearer $TOKEN" https://api.cloudflare.com/client/v4/user/tokens/verify`
- For Route 53: check IAM permissions and AWS region setting

**"HTTP 403 -- Invalid API token" from Cloudflare**
- Token lacks Zone:Read or DNS:Edit permission
- Token may be zone-scoped and not include the target zone
- Token may have been revoked

**Records not updating after save**
- Check the audit log -- if `result = 'error'`, the provider rejected the request
- The `error_message` column shows the original provider error message