/hetzner-dns

name: hetzner-dns
description: "Read and manage Hetzner DNS zones and records through gateway-proxied DNS API requests with guarded A, AAAA, CNAME, and TXT changes."
user-invocable: true
requires:
  bins:
    - node
credentials:
  - id: hetzner-dns-api-token
    kind: header
    required: true
    secret_ref:
      source: store
      id: HETZNER_DNS_API_TOKEN
    scope: "dns.hetzner.com/api/v1"
    how_to_obtain: "Create a DNS API access token in the Hetzner DNS Console. Set `HETZNER_DNS_API_TOKEN` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set HETZNER_DNS_API_TOKEN \"<hetzner-dns-api-token>\"` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set HETZNER_DNS_API_TOKEN \"<hetzner-dns-api-token>\"`. The helper injects it into the Auth-API-Token header server-side."
metadata:
  hybridclaw:
    category: infrastructure
    short_description: "Hetzner DNS zone and record reads plus guarded record changes."
    tags:
      - hetzner
      - dns
      - records
      - infrastructure
    stakes_tiers:
      green:
        - list-zones
        - get-zone
        - list-rrsets
        - get-rrset
      amber:
        - create-rrset
        - update-rrset
        - add-record
        - remove-record
      red:
        - delete-record
        - delete-rrset
        - delete-zone
    escalation:
      writes: confirm-each
      route: f14
    cost_measurement:
      system: UsageTotals
      sub_limit_key: hetzner-dns

Hetzner DNS

Use this skill for Hetzner DNS zone discovery and A, AAAA, CNAME, TXT, and other record management through the Hetzner DNS API.

Default Workflow

1. Read first: list zones, then list records for the target zone id. 2. The DNS API is record-id based. Use `list-rrsets` to discover existing record ids before update or delete requests. 3. Use `plan` before mutations so the operator can see the tier and required grant. 4. Treat `hetzner_dns.cjs` as the API wrapper. Do not handcraft Hetzner DNS API URLs, JSON bodies, tiers, or secret refs from memory. 5. For prompt/user testing, stop after `plan` or after helper `http-request` payload generation. Do not call the built-in `http_request` tool. 6. For real user requests that need live Hetzner DNS reads, pass the helper-emitted `httpRequest` object unchanged to `http_request`. The `secretHeaders` entry for `Auth-API-Token` is the secret reference; do not preflight it, inspect it, or ask the model for the token. 7. If a live `http_request` call returns 401 or 403, stop after that first failure. Do not retry, do not fan out to more endpoints, and ask the operator to set or verify `HETZNER_DNS_API_TOKEN`. 8. Require explicit operator grant before creating, updating, adding, removing, or deleting records. Pass `--operator-grant` only after that grant. 9. Never paste, print, or inspect `HETZNER_DNS_API_TOKEN`; the gateway injects it server-side as `Auth-API-Token`.

See [references/operator-setup.md](references/operator-setup.md) for DNS token setup, scope, autonomy defaults, and record-id handling.

Command Contract

node skills/hetzner-dns/hetzner_dns.cjs --help

Plan a DNS request without contacting Hetzner:

node skills/hetzner-dns/hetzner_dns.cjs --format json plan "Point demo-acme.example.com at the demo VPS"

Build read requests:

node skills/hetzner-dns/hetzner_dns.cjs --format json http-request list-zones
node skills/hetzner-dns/hetzner_dns.cjs --format json http-request list-rrsets --zone-id zone123 --name demo --type A
node skills/hetzner-dns/hetzner_dns.cjs --format json http-request get-rrset --record-id record123

Build guarded write requests:

node skills/hetzner-dns/hetzner_dns.cjs --format json http-request create-rrset \
  --zone-id zone123 --name demo --type A --ttl 300 --record 203.0.113.10 \
  --operator-grant

node skills/hetzner-dns/hetzner_dns.cjs --format json http-request update-rrset \
  --record-id record123 --zone-id zone123 --name demo --type A --ttl 300 --record 203.0.113.11 \
  --operator-grant

node skills/hetzner-dns/hetzner_dns.cjs --format json http-request delete-record \
  --record-id record123 --operator-grant

Working Rules

• `create-rrset` and `add-record` emit one DNS API record create request. For

multiple values, build one request per value.

• Use `update-rrset` only with an exact `--record-id` from a prior read.
• Use `remove-record`, `delete-record`, or `delete-rrset` only with an exact

`--record-id`.

• Do not modify generated SOA records or default NS records.
• Use `@` for apex records when the API requires a record name.
• Stop before red actions (`delete-record`, `delete-rrset`, `delete-zone`)

unless the operator grants the exact record id or zone id target.

• Cost per assistant run is recorded by HybridClaw `UsageTotals`; helper output

includes `costMeasurement.system = "UsageTotals"` for eval verification.

Eval Suite

node skills/hetzner-dns/hetzner_dns.cjs --format json eval-scenarios

The fixture at `evals/scenarios.json` contains 10 DNS scenarios covering zone reads, record reads, A/AAAA/CNAME/TXT changes, and guarded deletes.

Validation

python3 skills/skill-creator/scripts/quick_validate.py skills/hetzner-dns
node skills/hetzner-dns/hetzner_dns.cjs --help
node skills/hetzner-dns/hetzner_dns.cjs --format json eval-scenarios