coredns-rfc2136/plugin.go

// Package rfc2136 implements a CoreDNS plugin that accepts dynamic DNS
// updates per RFC 2136 (UPDATE opcode), authenticated via TSIG. The
// primary use case is self-hosted ACME DNS-01 cert automation: an ACME
// client (e.g. Caddy via caddy-dns/rfc2136) injects _acme-challenge TXT
// records into a delegated sub-zone that this plugin serves.
//
// Phase 1.3 status: store + query dispatch. ServeDNS now answers
// authoritatively for the configured zone(s) from the in-memory store
// (plus synthetic SOA/NS at apex). UPDATE handling still rejected —
// that lands in Phase 1.4. See plan at
//
//	~/.claude/plans/dood-does-coredns-offer-enumerated-piglet.md
package rfc2136

import (
	"context"
	"strings"

	"github.com/coredns/coredns/plugin"
	"github.com/miekg/dns"
)

// DefaultTTL is the TTL applied to dynamically-added records when the
// Corefile doesn't specify one. 60s matches the short-lived nature of
// ACME challenge TXT records and keeps stale answers from lingering in
// resolver caches.
const DefaultTTL uint32 = 60

// RFC2136 is the plugin handler. One instance per Corefile server block.
type RFC2136 struct {
	// Next is the downstream plugin in the chain.
	Next plugin.Handler

	// Zones is the set of canonical (dot-terminated, lowercase) zone
	// names this instance is authoritative for. Queries outside these
	// zones pass through to Next.
	Zones []string

	// TSIGKeys is keyed by canonical key name (lowercased, trailing
	// dot). Empty means TSIG is disabled — UPDATEs without TSIG are
	// rejected unconditionally in Phase 1.4.
	TSIGKeys map[string]tsigKey

	// TTL is applied to dynamically-injected records that don't carry
	// an explicit TTL in the UPDATE message.
	TTL uint32

	// PersistPath, when non-empty, names a file the plugin writes a
	// JSON snapshot of its in-memory store to on a periodic schedule.
	// Empty means in-memory only (acceptable for ACME challenges).
	PersistPath string

	// Nameserver is the host returned in synthetic NS records and as
	// the SOA's MNAME. Defaults (set in setup) to the first zone apex.
	Nameserver string

	// store holds the dynamic records. Always non-nil after setup.
	store *recordStore
}

// Name implements plugin.Handler.
func (p *RFC2136) Name() string { return "rfc2136" }

// ServeDNS implements plugin.Handler.
//
// Dispatch:
//
//	UPDATE opcode  → rejected with REFUSED (Phase 1.4 implements properly).
//	Query opcode:
//	  - Not in our zones    → pass to Next.
//	  - Apex SOA            → synthetic SOA.
//	  - Apex NS             → synthetic NS.
//	  - Match in store      → return RRset.
//	  - Name exists, wrong type → NODATA (NOERROR + SOA in authority).
//	  - Name doesn't exist  → NXDOMAIN (NameError + SOA in authority).
func (p *RFC2136) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error) {
	if r.Opcode == dns.OpcodeUpdate {
		// Phase 1.4 will dispatch to update handler. For now, refuse
		// loudly so clients know the plugin is loaded but not yet
		// accepting updates.
		return p.refuseUpdate(w, r)
	}

	if len(r.Question) == 0 {
		return plugin.NextOrFailure(p.Name(), p.Next, ctx, w, r)
	}

	q := r.Question[0]
	zone := p.findZone(q.Name)
	if zone == "" {
		return plugin.NextOrFailure(p.Name(), p.Next, ctx, w, r)
	}

	// We're authoritative for this name. Build a reply.
	msg := new(dns.Msg)
	msg.SetReply(r)
	msg.Authoritative = true

	qname := strings.ToLower(dns.Fqdn(q.Name))
	isApex := qname == zone

	// Apex SOA / NS are synthetic.
	if isApex {
		switch q.Qtype {
		case dns.TypeSOA:
			msg.Answer = []dns.RR{p.syntheticSOA(zone)}
			_ = w.WriteMsg(msg)
			return dns.RcodeSuccess, nil
		case dns.TypeNS:
			msg.Answer = p.syntheticNS(zone)
			_ = w.WriteMsg(msg)
			return dns.RcodeSuccess, nil
		}
	}

	// Look up the asked type in the store.
	if rrs := p.store.Lookup(qname, q.Qtype); rrs != nil {
		msg.Answer = rrs
		_ = w.WriteMsg(msg)
		return dns.RcodeSuccess, nil
	}

	// Special case: ANY at the apex isn't in the store but we have
	// synthetic SOA + NS. Return them rather than NODATA.
	if isApex && q.Qtype == dns.TypeANY {
		msg.Answer = append(msg.Answer, p.syntheticSOA(zone))
		msg.Answer = append(msg.Answer, p.syntheticNS(zone)...)
		_ = w.WriteMsg(msg)
		return dns.RcodeSuccess, nil
	}

	// Distinguish NODATA from NXDOMAIN.
	if p.store.NameExists(qname) || isApex {
		// NODATA: name exists, but not with this type.
		msg.Ns = []dns.RR{p.syntheticSOA(zone)}
		_ = w.WriteMsg(msg)
		return dns.RcodeSuccess, nil
	}

	// NXDOMAIN: name doesn't exist anywhere in this zone.
	msg.Rcode = dns.RcodeNameError
	msg.Ns = []dns.RR{p.syntheticSOA(zone)}
	_ = w.WriteMsg(msg)
	return dns.RcodeNameError, nil
}

// refuseUpdate returns REFUSED for UPDATE messages until Phase 1.4
// wires the proper UPDATE handler. We keep a dedicated method so the
// "this plugin doesn't yet accept updates" path is searchable in logs.
func (p *RFC2136) refuseUpdate(w dns.ResponseWriter, r *dns.Msg) (int, error) {
	log.Warningf("UPDATE opcode received but Phase 1.4 not yet implemented — refusing")
	msg := new(dns.Msg)
	msg.SetRcode(r, dns.RcodeRefused)
	_ = w.WriteMsg(msg)
	return dns.RcodeRefused, nil
}

// findZone returns the longest matching zone for qname, or "" if qname
// is outside all configured zones. The returned zone is in canonical
// form (lowercase, trailing dot).
func (p *RFC2136) findZone(qname string) string {
	qname = strings.ToLower(dns.Fqdn(qname))
	// Longest-suffix wins so nested zones work correctly.
	var best string
	for _, z := range p.Zones {
		if qname == z || strings.HasSuffix(qname, "."+z) {
			if len(z) > len(best) {
				best = z
			}
		}
	}
	return best
}

// syntheticSOA returns the SOA RR for a zone. Serial is derived from
// the store's monotonic generation counter — every UPDATE bumps it,
// so downstream observers can detect "something changed" without
// having to AXFR.
func (p *RFC2136) syntheticSOA(zone string) *dns.SOA {
	return &dns.SOA{
		Hdr: dns.RR_Header{
			Name:   zone,
			Rrtype: dns.TypeSOA,
			Class:  dns.ClassINET,
			Ttl:    p.TTL,
		},
		Ns:      p.Nameserver,
		Mbox:    "admin." + zone,
		Serial:  uint32(p.store.generation()),
		Refresh: 3600,    // 1 hour
		Retry:   600,     // 10 min
		Expire:  604800,  // 1 week
		Minttl:  60,      // negative-cache TTL
	}
}

// syntheticNS returns the NS RRset for a zone. Currently a single NS
// pointing at p.Nameserver (the host that runs this plugin). For
// resiliency, future versions could accept multiple `nameserver`
// directives.
func (p *RFC2136) syntheticNS(zone string) []dns.RR {
	return []dns.RR{
		&dns.NS{
			Hdr: dns.RR_Header{
				Name:   zone,
				Rrtype: dns.TypeNS,
				Class:  dns.ClassINET,
				Ttl:    p.TTL,
			},
			Ns: p.Nameserver,
		},
	}
}