From 1b2d6ec2b8315293b387e37cfdbb375c6b52c7ec Mon Sep 17 00:00:00 2001
From: Bretton <brettmay0212@gmail.com>
Date: Fri, 2 Oct 2026 02:12:10 -0700
Subject: [PATCH] feat(delegation): reconcile Cloudflare NS delegations for
 bridged instances

Add internal/delegation: a Cloudflare client and a reconcile pass that
lists the zone's NS records, compares them with the instance labels that
have live bridged actors, and creates the missing
<label>.<BRIDGE_HOSTNAME> NS record pointing at the first configured
nameserver. The pass never deletes. A label whose apex NS points
elsewhere is reported as conflicting and left alone, and delegations
without live actors are reported. Create failures do not stop the pass,
and an incomplete or over-long NS listing aborts it before any create.

CLOUDFLARE_API_TOKEN and CLOUDFLARE_ZONE_ID enable it; startup is
refused when the token is set without the zone ID or without
DNS_LISTEN. When enabled, Tidepool runs one pass in the background at
startup through the guarded HTTP client. The token is never logged.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 README.md                              |   2 +
 cmd/tidepool/delegation_test.go        | 261 ++++++++++++++
 cmd/tidepool/main.go                   |  41 +++
 cmd/tidepool/main_test.go              |   2 +
 internal/config/config.go              |  14 +
 internal/config/config_test.go         |  39 +++
 internal/delegation/client.go          | 158 +++++++++
 internal/delegation/reconciler.go      | 190 ++++++++++
 internal/delegation/reconciler_test.go | 461 +++++++++++++++++++++++++
 internal/store/bridged_actors.go       |  32 ++
 internal/store/bridged_actors_test.go  |  39 +++
 internal/store/interfaces.go           |   4 +
 internal/store/models.go               |   7 +
 13 files changed, 1250 insertions(+)
 create mode 100644 cmd/tidepool/delegation_test.go
 create mode 100644 internal/delegation/client.go
 create mode 100644 internal/delegation/reconciler.go
 create mode 100644 internal/delegation/reconciler_test.go

diff --git a/README.md b/README.md
index 33e0e4c..5a38531 100644
--- a/README.md
+++ b/README.md
@@ -323,6 +323,8 @@ Two classes, and the difference matters at boot:
 | `DNS_PUBLIC_IPV4` | *(unset)* | IPv4 address returned in A answers; required when `DNS_LISTEN` is set |
 | `DNS_PUBLIC_IPV6` | *(unset)* | optional IPv6 address returned in AAAA answers when DNS is enabled |
 | `DNS_NAMESERVERS` | `ns1`/`ns2` under `BRIDGE_HOSTNAME` when DNS is enabled | comma-separated nameserver hostnames returned in apex NS answers (first is the SOA primary) |
+| `CLOUDFLARE_API_TOKEN` | *(empty; disabled)* | Cloudflare API token with DNS edit on the zone; enables a startup pass creating `<label>.<BRIDGE_HOSTNAME> NS <first DNS_NAMESERVERS entry>` records. Requires `DNS_LISTEN` and `CLOUDFLARE_ZONE_ID`; empty disables delegation |
+| `CLOUDFLARE_ZONE_ID` | *(unset)* | zone ID of the zone holding `BRIDGE_HOSTNAME`; required when `CLOUDFLARE_API_TOKEN` is set |
 | `BRIDGE_SCHEME` | `https` | scheme of the bridge's own AP URLs (actor id, inbox, activity ids). `http` is dev-only — the e2e harness federates with a debug-mode Lemmy over plain HTTP |
 | `PLC_DIRECTORY_URL` | `http://localhost:3002` (local, `make plc-up`) | did:plc directory; production uses `https://plc.directory` |
 | `BRIDGE_KEK` | fixed public dev key | 32-byte key-encryption key (64 hex chars or base64) sealing per-actor signing keys and the escrow rotation key at rest (AES-256-GCM) |
diff --git a/cmd/tidepool/delegation_test.go b/cmd/tidepool/delegation_test.go
new file mode 100644
index 0000000..4edac3b
--- /dev/null
+++ b/cmd/tidepool/delegation_test.go
@@ -0,0 +1,261 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"tidepool/internal/config"
+	"tidepool/internal/delegation"
+	"tidepool/internal/store"
+	"tidepool/internal/testutil"
+)
+
+type startupCloudflareRequest struct {
+	Method        string
+	Path          string
+	Query         string
+	Authorization string
+	Body          map[string]any
+}
+
+type startupCloudflareAPI struct {
+	server       *httptest.Server
+	firstGET     chan struct{}
+	releaseGET   chan struct{}
+	releaseOnce  sync.Once
+	post         chan startupCloudflareRequest
+	mutex        sync.Mutex
+	requests     []startupCloudflareRequest
+	unauthorized bool
+	blockFirst   bool
+}
+
+func newStartupCloudflareAPI(t *testing.T, blockFirst bool) *startupCloudflareAPI {
+	t.Helper()
+	fake := &startupCloudflareAPI{
+		firstGET:   make(chan struct{}),
+		releaseGET: make(chan struct{}),
+		post:       make(chan startupCloudflareRequest, 1),
+		blockFirst: blockFirst,
+	}
+	fake.server = httptest.NewServer(http.HandlerFunc(fake.serveHTTP))
+	t.Cleanup(func() {
+		fake.release()
+		fake.server.Close()
+	})
+	return fake
+}
+
+func (fake *startupCloudflareAPI) release() {
+	fake.releaseOnce.Do(func() { close(fake.releaseGET) })
+}
+
+func (fake *startupCloudflareAPI) snapshot() ([]startupCloudflareRequest, bool) {
+	fake.mutex.Lock()
+	defer fake.mutex.Unlock()
+	return append([]startupCloudflareRequest(nil), fake.requests...), fake.unauthorized
+}
+
+func (fake *startupCloudflareAPI) serveHTTP(w http.ResponseWriter, r *http.Request) {
+	request := startupCloudflareRequest{
+		Method:        r.Method,
+		Path:          r.URL.Path,
+		Query:         r.URL.RawQuery,
+		Authorization: r.Header.Get("Authorization"),
+	}
+	if r.Method == http.MethodPost {
+		if err := json.NewDecoder(r.Body).Decode(&request.Body); err != nil {
+			w.WriteHeader(http.StatusBadRequest)
+			return
+		}
+	}
+	fake.mutex.Lock()
+	fake.requests = append(fake.requests, request)
+	first := len(fake.requests) == 1 && r.Method == http.MethodGet
+	if request.Authorization != "Bearer cf-startup-token" {
+		fake.unauthorized = true
+	}
+	fake.mutex.Unlock()
+	if first {
+		close(fake.firstGET)
+		if fake.blockFirst {
+			select {
+			case <-fake.releaseGET:
+			case <-r.Context().Done():
+				return
+			}
+		}
+	}
+	w.Header().Set("Content-Type", "application/json")
+	if request.Authorization != "Bearer cf-startup-token" {
+		w.WriteHeader(http.StatusForbidden)
+		_, _ = w.Write([]byte(`{"success":false,"errors":[{"code":9109,"message":"unauthorized"}],"messages":[],"result":null}`))
+		return
+	}
+	if r.URL.Path != "/client/v4/zones/zone-startup/dns_records" {
+		w.WriteHeader(http.StatusNotFound)
+		return
+	}
+	switch r.Method {
+	case http.MethodGet:
+		_, _ = w.Write([]byte(`{"success":true,"errors":[],"messages":[],"result":[],"result_info":{"page":1,"per_page":2,"count":0,"total_count":0,"total_pages":1}}`))
+	case http.MethodPost:
+		_, _ = w.Write([]byte(`{"success":true,"errors":[],"messages":[],"result":{"id":"new-record","type":"NS","name":"lemmy-example.tdpl.example","content":"a.ns.example","ttl":3600}}`))
+		fake.post <- request
+	default:
+		w.WriteHeader(http.StatusMethodNotAllowed)
+	}
+}
+
+func startupDelegationConfig(allowPrivate bool) *config.Config {
+	return &config.Config{
+		BridgeHostname:        "tdpl.example",
+		DNSListen:             "127.0.0.1:5300",
+		DNSNameservers:        []string{"a.ns.example", "b.ns.example"},
+		CloudflareAPIToken:    "cf-startup-token",
+		CloudflareZoneID:      "zone-startup",
+		AllowPrivateAddresses: allowPrivate,
+	}
+}
+
+func TestStartDelegationStartsBackgroundPass(t *testing.T) {
+	conn := testutil.DB(t)
+	testutil.Truncate(t, conn, "bridged_actors")
+	actors := store.NewBridgedActors(conn)
+	ctx, cancel := context.WithCancel(context.Background())
+	t.Cleanup(cancel)
+	_, err := actors.UpsertActor(ctx, store.BridgedActor{
+		APActorID:    "https://lemmy.example/u/alice-startup",
+		ActorType:    store.ActorTypePerson,
+		DID:          "did:plc:cmddelegationstart000000001",
+		Handle:       "alice.lemmy-example.tdpl.example",
+		ConsentState: store.ConsentStateOK,
+	})
+	require.NoError(t, err)
+
+	fake := newStartupCloudflareAPI(t, true)
+	type startupResult struct {
+		reconciler *delegation.Reconciler
+		err        error
+	}
+	returned := make(chan startupResult, 1)
+	go func() {
+		reconciler, err := startDelegation(ctx, startupDelegationConfig(true), actors,
+			fake.server.URL+"/client/v4", testLogger())
+		returned <- startupResult{reconciler, err}
+	}()
+	// Whichever happens first, the returned value must be valid and the GET
+	// must start; the GET stays blocked until after both conditions hold.
+	returnedAlready := false
+	select {
+	case result := <-returned:
+		require.NoError(t, result.err)
+		require.NotNil(t, result.reconciler)
+		returnedAlready = true
+	case <-fake.firstGET:
+	case <-time.After(5 * time.Second):
+		t.Fatal("neither startDelegation returned nor the background GET started")
+	}
+	select {
+	case <-fake.firstGET:
+	case <-time.After(5 * time.Second):
+		t.Fatal("background pass never sent its first listing GET")
+	}
+	if !returnedAlready {
+		select {
+		case result := <-returned:
+			require.NoError(t, result.err)
+			require.NotNil(t, result.reconciler, "startDelegation must return before the listing GET finishes")
+		case <-time.After(5 * time.Second):
+			t.Fatal("startDelegation blocked on the held listing GET")
+		}
+	}
+	fake.release()
+	select {
+	case request := <-fake.post:
+		assert.Equal(t, http.MethodPost, request.Method)
+		assert.Equal(t, "/client/v4/zones/zone-startup/dns_records", request.Path)
+		assert.Equal(t, "Bearer cf-startup-token", request.Authorization)
+		assert.Equal(t, "NS", request.Body["type"])
+		assert.Equal(t, "lemmy-example.tdpl.example", request.Body["name"])
+		assert.Equal(t, "a.ns.example", request.Body["content"])
+		assert.Equal(t, float64(3600), request.Body["ttl"])
+		assert.NotContains(t, request.Body, "proxied")
+	case <-time.After(5 * time.Second):
+		t.Fatal("background pass did not create the delegation")
+	}
+	requests, unauthorized := fake.snapshot()
+	assert.False(t, unauthorized, "every Cloudflare request must use the configured bearer token")
+	for _, request := range requests {
+		assert.Equal(t, "/client/v4/zones/zone-startup/dns_records", request.Path)
+		assert.Equal(t, "Bearer cf-startup-token", request.Authorization)
+		assert.Contains(t, []string{http.MethodGet, http.MethodPost}, request.Method)
+	}
+}
+
+func TestStartDelegationDisabledWithoutToken(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	t.Cleanup(cancel)
+	fake := newStartupCloudflareAPI(t, false)
+	cfg := startupDelegationConfig(true)
+	cfg.CloudflareAPIToken = ""
+	reconciler, err := startDelegation(ctx, cfg, nil, fake.server.URL+"/client/v4", testLogger())
+	require.NoError(t, err)
+	assert.Nil(t, reconciler)
+	requests, _ := fake.snapshot()
+	assert.Empty(t, requests)
+}
+
+type startupLabelSource struct {
+	store.BridgedActors
+}
+
+func (startupLabelSource) ListInstanceLabels(context.Context, string) ([]store.InstanceLabel, error) {
+	return []store.InstanceLabel{{Label: "lemmy-example", HasLiveActor: true}}, nil
+}
+
+type startupErrorSignal struct {
+	slog.Handler
+	errors chan slog.Record
+}
+
+func (handler startupErrorSignal) Handle(ctx context.Context, record slog.Record) error {
+	err := handler.Handler.Handle(ctx, record)
+	if record.Level == slog.LevelError {
+		select {
+		case handler.errors <- record.Clone():
+		default:
+		}
+	}
+	return err
+}
+
+func TestStartDelegationGuardsPrivateAddresses(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	t.Cleanup(cancel)
+	fake := newStartupCloudflareAPI(t, false)
+	logger, _ := capturingLogger()
+	errors := make(chan slog.Record, 1)
+	logger = slog.New(startupErrorSignal{Handler: logger.Handler(), errors: errors})
+	reconciler, err := startDelegation(ctx, startupDelegationConfig(false), startupLabelSource{},
+		fake.server.URL+"/client/v4", logger)
+	require.NoError(t, err)
+	require.NotNil(t, reconciler)
+	select {
+	case record := <-errors:
+		assert.Equal(t, slog.LevelError, record.Level)
+	case <-time.After(5 * time.Second):
+		t.Fatal("background pass did not log its guarded-client failure")
+	}
+	requests, _ := fake.snapshot()
+	assert.Empty(t, requests, "the guarded client must refuse loopback before reaching Cloudflare")
+}
diff --git a/cmd/tidepool/main.go b/cmd/tidepool/main.go
index c01b219..e461322 100644
--- a/cmd/tidepool/main.go
+++ b/cmd/tidepool/main.go
@@ -27,6 +27,7 @@ import (
 	"tidepool/internal/config"
 	"tidepool/internal/consume"
 	"tidepool/internal/db"
+	"tidepool/internal/delegation"
 	"tidepool/internal/dns"
 	"tidepool/internal/echo"
 	"tidepool/internal/identity"
@@ -276,6 +277,9 @@ func run(logger *slog.Logger) error {
 	if err != nil {
 		return err
 	}
+	if _, err := startDelegation(ctx, cfg, actors, delegation.CloudflareAPIBaseURL, logger); err != nil {
+		return fmt.Errorf("delegation: %w", err)
+	}
 	router.Get("/xrpc/com.atproto.identity.resolveHandle", identity.ResolveHandleHandler(resolver, logger))
 	router.Get("/.well-known/atproto-did", identity.WellKnownDIDHandler(resolver, logger))
 	// Cert-issuance gate for TLS-terminating proxies with on-demand
@@ -1043,3 +1047,40 @@ func startDNSServer(ctx context.Context, cfg *config.Config, resolver identity.R
 	logger.Info("dns server listening", "addr", cfg.DNSListen, "zone_root", cfg.BridgeHostname)
 	return serveErrors, nil
 }
+
+// startDelegation starts one asynchronous delegation pass when a Cloudflare
+// token is configured, returning the reconciler without waiting for the pass.
+func startDelegation(ctx context.Context, cfg *config.Config, actors store.BridgedActors, cloudflareBaseURL string, logger *slog.Logger) (*delegation.Reconciler, error) {
+	if cfg.CloudflareAPIToken == "" {
+		return nil, nil
+	}
+	client, err := delegation.NewCloudflareClient(delegation.CloudflareOptions{
+		BaseURL:    cloudflareBaseURL,
+		Token:      cfg.CloudflareAPIToken,
+		ZoneID:     cfg.CloudflareZoneID,
+		HTTPClient: ap.NewGuardedHTTPClient(cfg.AllowPrivateAddresses, 30*time.Second),
+	})
+	if err != nil {
+		return nil, fmt.Errorf("create Cloudflare client: %w", err)
+	}
+	reconciler, err := delegation.NewReconciler(delegation.Options{
+		Client: client, Labels: actors, ZoneRoot: cfg.BridgeHostname,
+		Nameservers: cfg.DNSNameservers, Logger: logger,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("create delegation reconciler: %w", err)
+	}
+	go func() {
+		result, err := reconciler.Reconcile(ctx)
+		logger.InfoContext(ctx, "startup delegation pass finished", "component", "delegation",
+			"created_count", len(result.Created), "created", result.Created,
+			"already_delegated_count", len(result.AlreadyDelegated),
+			"conflicting_count", len(result.Conflicting), "conflicting", result.Conflicting,
+			"failed_count", len(result.Failed), "failed", result.Failed,
+			"delegated_without_live_actors_count", len(result.DelegatedWithoutLiveActors))
+		if err != nil {
+			logger.ErrorContext(ctx, "startup delegation pass failed", "component", "delegation", "error", err)
+		}
+	}()
+	return reconciler, nil
+}
diff --git a/cmd/tidepool/main_test.go b/cmd/tidepool/main_test.go
index 401f51b..c40e1f4 100644
--- a/cmd/tidepool/main_test.go
+++ b/cmd/tidepool/main_test.go
@@ -142,6 +142,8 @@ func TestRunDNSBindFailurePrecedesHTTP(t *testing.T) {
 			t.Setenv("DNS_PUBLIC_IPV4", "127.0.0.1")
 			t.Setenv("DNS_PUBLIC_IPV6", "")
 			t.Setenv("DNS_NAMESERVERS", "")
+			t.Setenv("CLOUDFLARE_API_TOKEN", "")
+			t.Setenv("CLOUDFLARE_ZONE_ID", "")
 			t.Setenv("BRIDGE_HOSTNAME", "tdpl.example")
 			t.Setenv("BRIDGE_KEK", rotateTestKEK)
 			t.Setenv("BRIDGE_KEK_PREVIOUS", "")
diff --git a/internal/config/config.go b/internal/config/config.go
index 7a46e11..f93e3e5 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -43,6 +43,10 @@ type Config struct {
 	DNSPublicIPv4  netip.Addr
 	DNSPublicIPv6  netip.Addr
 	DNSNameservers []string
+	// CloudflareAPIToken enables the startup delegation pass when set.
+	CloudflareAPIToken string
+	// CloudflareZoneID identifies the zone containing BridgeHostname.
+	CloudflareZoneID string
 	// BridgeScheme is the URL scheme the bridge's own AP URLs (service
 	// actor id, inbox, activity ids, nodeinfo) are built with. BRIDGE_SCHEME,
 	// default "https". "http" is only accepted in development — it exists for
@@ -351,6 +355,16 @@ func Load(logger *slog.Logger) (*Config, error) {
 			cfg.DNSNameservers = []string{"ns1." + root, "ns2." + root}
 		}
 	}
+	cfg.CloudflareAPIToken = strings.TrimSpace(os.Getenv("CLOUDFLARE_API_TOKEN"))
+	cfg.CloudflareZoneID = strings.TrimSpace(os.Getenv("CLOUDFLARE_ZONE_ID"))
+	if cfg.CloudflareAPIToken != "" {
+		if cfg.CloudflareZoneID == "" {
+			return nil, fmt.Errorf("config: CLOUDFLARE_ZONE_ID is required when CLOUDFLARE_API_TOKEN is set")
+		}
+		if cfg.DNSListen == "" {
+			return nil, fmt.Errorf("config: DNS_LISTEN is required when CLOUDFLARE_API_TOKEN is set")
+		}
+	}
 	cfg.PLCDirectoryURL, err = stringVar(logger, isDevelopment, "PLC_DIRECTORY_URL", "http://localhost:3002")
 	if err != nil {
 		return nil, err
diff --git a/internal/config/config_test.go b/internal/config/config_test.go
index 6284074..fd24ec6 100644
--- a/internal/config/config_test.go
+++ b/internal/config/config_test.go
@@ -21,6 +21,7 @@ func clearConfigEnv(t *testing.T) {
 	for _, name := range []string{
 		"ENVIRONMENT", "DATABASE_URL", "LISTEN_ADDR", "BRIDGE_HOSTNAME",
 		"DNS_LISTEN", "DNS_PUBLIC_IPV4", "DNS_PUBLIC_IPV6", "DNS_NAMESERVERS",
+		"CLOUDFLARE_API_TOKEN", "CLOUDFLARE_ZONE_ID",
 		"PLC_DIRECTORY_URL", "BRIDGE_SERVICE_DID", "USER_AGENT", "BRIDGE_KEK",
 		"BRIDGE_KEK_PREVIOUS",
 		"ADMIN_TOKEN", "BACKFILL_MAX_POSTS", "MINT_RATE_PER_MINUTE",
@@ -148,6 +149,44 @@ func TestLoad_DNSAcceptsSingleLabelZoneRoot(t *testing.T) {
 	require.Equal(t, []string{"ns1.localhost", "ns2.localhost"}, cfg.DNSNameservers)
 }
 
+func TestLoad_CloudflareDelegationConfiguration(t *testing.T) {
+	for _, tc := range []struct {
+		name       string
+		token      string
+		zoneID     string
+		dnsEnabled bool
+		wantErrors []string
+	}{
+		{name: "token unset disables delegation"},
+		{name: "token requires zone ID", token: "cf-config-token", dnsEnabled: true, wantErrors: []string{"CLOUDFLARE_ZONE_ID"}},
+		{name: "token requires DNS listener", token: "cf-config-token", zoneID: "zone-config", wantErrors: []string{"CLOUDFLARE_API_TOKEN", "DNS_LISTEN"}},
+		{name: "enabled values are carried", token: "cf-config-token", zoneID: "zone-config", dnsEnabled: true},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			clearConfigEnv(t)
+			t.Setenv("CLOUDFLARE_API_TOKEN", tc.token)
+			t.Setenv("CLOUDFLARE_ZONE_ID", tc.zoneID)
+			if tc.dnsEnabled {
+				t.Setenv("BRIDGE_HOSTNAME", "localhost")
+				t.Setenv("DNS_LISTEN", "127.0.0.1:5300")
+				t.Setenv("DNS_PUBLIC_IPV4", "127.0.0.1")
+			}
+
+			cfg, err := Load(discardLogger())
+			if len(tc.wantErrors) > 0 {
+				require.Error(t, err)
+				for _, name := range tc.wantErrors {
+					assert.Contains(t, err.Error(), name)
+				}
+				return
+			}
+			require.NoError(t, err)
+			assert.Equal(t, tc.token, cfg.CloudflareAPIToken)
+			assert.Equal(t, tc.zoneID, cfg.CloudflareZoneID)
+		})
+	}
+}
+
 func TestLoad_BridgeHostnameWithPortLoadsWhenDNSDisabled(t *testing.T) {
 	clearConfigEnv(t)
 	t.Setenv("BRIDGE_HOSTNAME", "tdpl.io:443")
diff --git a/internal/delegation/client.go b/internal/delegation/client.go
new file mode 100644
index 0000000..b8fb8d7
--- /dev/null
+++ b/internal/delegation/client.go
@@ -0,0 +1,158 @@
+// Package delegation reconciles bridged instance labels with Cloudflare NS
+// records for the bridge's DNS zone.
+package delegation
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+)
+
+// CloudflareAPIBaseURL is the production Cloudflare v4 API endpoint.
+const CloudflareAPIBaseURL = "https://api.cloudflare.com/client/v4"
+
+const maximumResponseBytes = 1 << 20
+
+// maximumListingPages bounds the NS listing at 10,000 records, well above the
+// zone's record quota.
+const maximumListingPages = 100
+
+// CloudflareOptions configures the Cloudflare DNS client. HTTPClient must be
+// supplied by the caller with the appropriate outbound-address guard.
+type CloudflareOptions struct {
+	BaseURL    string
+	Token      string
+	ZoneID     string
+	HTTPClient *http.Client
+}
+
+// CloudflareClient lists and creates DNS records in a Cloudflare zone.
+type CloudflareClient struct {
+	baseURL    string
+	token      string
+	zoneID     string
+	httpClient *http.Client
+}
+
+// NewCloudflareClient validates options and creates a Cloudflare DNS client.
+func NewCloudflareClient(options CloudflareOptions) (*CloudflareClient, error) {
+	if strings.TrimSpace(options.BaseURL) == "" || strings.TrimSpace(options.Token) == "" || strings.TrimSpace(options.ZoneID) == "" || options.HTTPClient == nil {
+		return nil, fmt.Errorf("Cloudflare base URL, token, zone ID and HTTP client are required")
+	}
+	return &CloudflareClient{
+		baseURL: strings.TrimRight(options.BaseURL, "/"),
+		token:   options.Token, zoneID: options.ZoneID, httpClient: options.HTTPClient,
+	}, nil
+}
+
+type dnsRecord struct {
+	Type    string `json:"type"`
+	Name    string `json:"name"`
+	Content string `json:"content"`
+}
+
+type apiResponse struct {
+	Success bool `json:"success"`
+	Errors  []struct {
+		Message string `json:"message"`
+	} `json:"errors"`
+	Result     json.RawMessage `json:"result"`
+	ResultInfo *struct {
+		TotalPages int `json:"total_pages"`
+	} `json:"result_info"`
+}
+
+func (c *CloudflareClient) recordsURL() string {
+	return c.baseURL + "/zones/" + url.PathEscape(c.zoneID) + "/dns_records"
+}
+
+func (c *CloudflareClient) request(ctx context.Context, method, endpoint string, body []byte) (apiResponse, error) {
+	var response apiResponse
+	request, err := http.NewRequestWithContext(ctx, method, endpoint, bytes.NewReader(body))
+	if err != nil {
+		return response, fmt.Errorf("build Cloudflare DNS request: %w", err)
+	}
+	request.Header.Set("Authorization", "Bearer "+c.token)
+	request.Header.Set("Accept", "application/json")
+	if body != nil {
+		request.Header.Set("Content-Type", "application/json")
+	}
+	result, err := c.httpClient.Do(request)
+	if err != nil {
+		return response, fmt.Errorf("send Cloudflare DNS request: %w", err)
+	}
+	defer result.Body.Close()
+	data, err := io.ReadAll(io.LimitReader(result.Body, maximumResponseBytes+1))
+	if err != nil {
+		return response, fmt.Errorf("read Cloudflare DNS response: %w", err)
+	}
+	if len(data) > maximumResponseBytes {
+		return response, fmt.Errorf("Cloudflare DNS response exceeds %d bytes", maximumResponseBytes)
+	}
+	if err := json.Unmarshal(data, &response); err != nil {
+		return response, fmt.Errorf("decode Cloudflare DNS response (HTTP %d): %w", result.StatusCode, err)
+	}
+	if result.StatusCode < 200 || result.StatusCode >= 300 || !response.Success {
+		messages := make([]string, 0, len(response.Errors))
+		for _, apiError := range response.Errors {
+			if apiError.Message != "" {
+				messages = append(messages, apiError.Message)
+			}
+		}
+		if len(messages) == 0 {
+			return response, fmt.Errorf("Cloudflare DNS request failed (HTTP %d)", result.StatusCode)
+		}
+		return response, fmt.Errorf("Cloudflare DNS request failed (HTTP %d): %s", result.StatusCode, strings.Join(messages, "; "))
+	}
+	return response, nil
+}
+
+func (c *CloudflareClient) listRecords(ctx context.Context) ([]dnsRecord, error) {
+	var records []dnsRecord
+	for page := 1; ; page++ {
+		query := url.Values{"type": {"NS"}, "per_page": {"100"}, "page": {fmt.Sprint(page)}}
+		response, err := c.request(ctx, http.MethodGet, c.recordsURL()+"?"+query.Encode(), nil)
+		if err != nil {
+			return nil, fmt.Errorf("list Cloudflare NS records on page %d: %w", page, err)
+		}
+		var pageRecords []dnsRecord
+		if err := json.Unmarshal(response.Result, &pageRecords); err != nil {
+			return nil, fmt.Errorf("decode Cloudflare NS records on page %d: %w", page, err)
+		}
+		if response.ResultInfo == nil {
+			return nil, fmt.Errorf("list Cloudflare NS records on page %d: response has no result_info", page)
+		}
+		totalPages := response.ResultInfo.TotalPages
+		if totalPages < 1 && len(pageRecords) > 0 {
+			return nil, fmt.Errorf("list Cloudflare NS records on page %d: result_info.total_pages is %d but the page returned %d records", page, totalPages, len(pageRecords))
+		}
+		records = append(records, pageRecords...)
+		if page >= totalPages {
+			return records, nil
+		}
+		if page >= maximumListingPages {
+			return nil, fmt.Errorf("list Cloudflare NS records: result_info.total_pages is %d, above the %d-page limit", totalPages, maximumListingPages)
+		}
+	}
+}
+
+func (c *CloudflareClient) createRecord(ctx context.Context, name, content string) error {
+	body, err := json.Marshal(struct {
+		Type    string `json:"type"`
+		Name    string `json:"name"`
+		Content string `json:"content"`
+		TTL     int    `json:"ttl"`
+	}{Type: "NS", Name: name, Content: content, TTL: 3600})
+	if err != nil {
+		return fmt.Errorf("encode Cloudflare NS record: %w", err)
+	}
+	if _, err := c.request(ctx, http.MethodPost, c.recordsURL(), body); err != nil {
+		return fmt.Errorf("create Cloudflare NS record %s: %w", name, err)
+	}
+	return nil
+}
diff --git a/internal/delegation/reconciler.go b/internal/delegation/reconciler.go
new file mode 100644
index 0000000..cf0da87
--- /dev/null
+++ b/internal/delegation/reconciler.go
@@ -0,0 +1,190 @@
+package delegation
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"sort"
+	"strings"
+
+	"tidepool/internal/store"
+)
+
+// LabelSource supplies distinct instance labels and their live-actor status.
+type LabelSource interface {
+	ListInstanceLabels(ctx context.Context, zoneRoot string) ([]store.InstanceLabel, error)
+}
+
+// Options configures a delegation reconciler for a DNS zone.
+type Options struct {
+	Client      *CloudflareClient
+	Labels      LabelSource
+	ZoneRoot    string
+	Nameservers []string
+	Logger      *slog.Logger
+}
+
+// Reconciler compares bridged instance labels with Cloudflare NS records and
+// creates missing delegations without modifying existing records.
+type Reconciler struct {
+	client      *CloudflareClient
+	labels      LabelSource
+	zoneRoot    string
+	nameservers []string
+	logger      *slog.Logger
+}
+
+func normalizeDNSName(name string) string {
+	return strings.TrimRight(strings.ToLower(name), ".")
+}
+
+// NewReconciler validates options and normalizes the zone and nameservers.
+func NewReconciler(options Options) (*Reconciler, error) {
+	if options.Client == nil || options.Labels == nil || normalizeDNSName(options.ZoneRoot) == "" || len(options.Nameservers) == 0 {
+		return nil, fmt.Errorf("delegation client, label source, zone root and nameservers are required")
+	}
+	nameservers := make([]string, len(options.Nameservers))
+	for index, nameserver := range options.Nameservers {
+		nameservers[index] = normalizeDNSName(nameserver)
+		if nameservers[index] == "" {
+			return nil, fmt.Errorf("delegation nameserver at index %d is empty", index)
+		}
+	}
+	logger := options.Logger
+	if logger == nil {
+		logger = slog.New(slog.NewTextHandler(io.Discard, nil))
+	}
+	return &Reconciler{
+		client: options.Client, labels: options.Labels, zoneRoot: normalizeDNSName(options.ZoneRoot),
+		nameservers: nameservers, logger: logger,
+	}, nil
+}
+
+// Result summarizes a completed pass. Labels in every field are bare,
+// lowercased DNS labels rather than fully qualified names.
+type Result struct {
+	// Created contains live labels for which an NS record was created.
+	Created []string
+	// AlreadyDelegated contains live labels with a configured NS record.
+	AlreadyDelegated []string
+	// Conflicting contains labels with foreign NS records, including labels
+	// that also have a configured NS record.
+	Conflicting []Conflict
+	// Failed contains live labels whose NS record could not be created.
+	Failed []Failure
+	// DelegatedWithoutLiveActors contains labels with configured NS records
+	// but no live actors and no foreign NS records.
+	DelegatedWithoutLiveActors []string
+}
+
+// Conflict identifies a label and the foreign nameservers in its NS records.
+type Conflict struct {
+	Label    string
+	Contents []string
+}
+
+// Failure identifies a label whose NS record could not be created and why.
+type Failure struct {
+	Label  string
+	Reason string
+}
+
+// Reconcile lists all instance labels and zone NS records, then creates only
+// the missing delegations for live labels. It reports create failures after
+// attempting the remaining labels.
+func (r *Reconciler) Reconcile(ctx context.Context) (Result, error) {
+	var result Result
+	labels, err := r.labels.ListInstanceLabels(ctx, r.zoneRoot)
+	if err != nil {
+		return result, fmt.Errorf("list instance labels for %s: %w", r.zoneRoot, err)
+	}
+	records, err := r.client.listRecords(ctx)
+	if err != nil {
+		return result, fmt.Errorf("list delegations for %s: %w", r.zoneRoot, err)
+	}
+
+	liveLabels := make(map[string]bool, len(labels))
+	for _, label := range labels {
+		name := normalizeDNSName(label.Label)
+		liveLabels[name] = liveLabels[name] || label.HasLiveActor
+	}
+	configured := make(map[string]bool, len(r.nameservers))
+	for _, nameserver := range r.nameservers {
+		configured[nameserver] = true
+	}
+	type delegationState struct {
+		delegated bool
+		foreign   []string
+	}
+	delegations := make(map[string]*delegationState)
+	for _, record := range records {
+		if !strings.EqualFold(record.Type, "NS") {
+			continue
+		}
+		name := normalizeDNSName(record.Name)
+		label, ok := strings.CutSuffix(name, "."+r.zoneRoot)
+		if !ok || label == "" || strings.Contains(label, ".") {
+			continue
+		}
+		state := delegations[label]
+		if state == nil {
+			state = &delegationState{}
+			delegations[label] = state
+		}
+		content := normalizeDNSName(record.Content)
+		if configured[content] {
+			state.delegated = true
+		} else {
+			state.foreign = append(state.foreign, content)
+		}
+	}
+
+	allLabels := make(map[string]bool, len(liveLabels)+len(delegations))
+	for label := range liveLabels {
+		allLabels[label] = true
+	}
+	for label := range delegations {
+		allLabels[label] = true
+	}
+	orderedLabels := make([]string, 0, len(allLabels))
+	for label := range allLabels {
+		orderedLabels = append(orderedLabels, label)
+	}
+	sort.Strings(orderedLabels)
+	var failures []error
+	for _, label := range orderedLabels {
+		state := delegations[label]
+		if state != nil {
+			if state.delegated && liveLabels[label] {
+				result.AlreadyDelegated = append(result.AlreadyDelegated, label)
+			}
+			if len(state.foreign) != 0 {
+				result.Conflicting = append(result.Conflicting, Conflict{Label: label, Contents: state.foreign})
+				r.logger.WarnContext(ctx, "foreign NS delegation", "label", label, "contents", state.foreign)
+				continue
+			}
+			if state.delegated {
+				if !liveLabels[label] {
+					result.DelegatedWithoutLiveActors = append(result.DelegatedWithoutLiveActors, label)
+					r.logger.InfoContext(ctx, "delegation without live actors", "label", label)
+				}
+				continue
+			}
+		}
+		if !liveLabels[label] {
+			continue
+		}
+		if err := r.client.createRecord(ctx, label+"."+r.zoneRoot, r.nameservers[0]); err != nil {
+			result.Failed = append(result.Failed, Failure{Label: label, Reason: err.Error()})
+			failures = append(failures, err)
+			r.logger.ErrorContext(ctx, "create NS delegation failed", "label", label, "error", err)
+			continue
+		}
+		result.Created = append(result.Created, label)
+	}
+	r.logger.InfoContext(ctx, "delegation pass complete", "created", len(result.Created), "already_delegated", len(result.AlreadyDelegated),
+		"conflicting", len(result.Conflicting), "failed", len(result.Failed), "delegated_without_live_actors", len(result.DelegatedWithoutLiveActors))
+	return result, errors.Join(failures...)
+}
diff --git a/internal/delegation/reconciler_test.go b/internal/delegation/reconciler_test.go
new file mode 100644
index 0000000..2a8c636
--- /dev/null
+++ b/internal/delegation/reconciler_test.go
@@ -0,0 +1,461 @@
+package delegation
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strconv"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+
+	"tidepool/internal/ap"
+	"tidepool/internal/store"
+)
+
+const (
+	delegationZoneRoot = "tdpl.example"
+	delegationZoneID   = "zone-123"
+	delegationToken    = "cf-test-token-7f3a"
+	delegationPath     = "/client/v4/zones/zone-123/dns_records"
+)
+
+type fakeLabelSource struct {
+	labels []store.InstanceLabel
+	err    error
+}
+
+func (s fakeLabelSource) ListInstanceLabels(_ context.Context, _ string) ([]store.InstanceLabel, error) {
+	return s.labels, s.err
+}
+
+type fakeDNSRecord struct {
+	ID      string `json:"id"`
+	Type    string `json:"type"`
+	Name    string `json:"name"`
+	Content string `json:"content"`
+	TTL     int    `json:"ttl"`
+}
+
+type fakeCloudflareRequest struct {
+	Method        string
+	Path          string
+	Query         url.Values
+	Authorization string
+	Body          map[string]any
+}
+
+type fakeCloudflareAPI struct {
+	mu              sync.Mutex
+	server          *httptest.Server
+	records         []fakeDNSRecord
+	requests        []fakeCloudflareRequest
+	listingFailPage int
+	listingFailCode int
+	listingFailBody string
+	createFailCode  int
+	createFailBody  string
+	failedPostLabel string
+	postCount       int
+	// pageSize overrides the default listing page size when positive.
+	pageSize int
+	// omitResultInfo drops result_info from listing responses.
+	omitResultInfo bool
+	// reportedTotalPages overrides result_info.total_pages when positive.
+	reportedTotalPages int
+}
+
+func newFakeCloudflareAPI(t *testing.T, records []fakeDNSRecord) *fakeCloudflareAPI {
+	t.Helper()
+	fake := &fakeCloudflareAPI{records: append([]fakeDNSRecord{}, records...)}
+	fake.server = httptest.NewServer(http.HandlerFunc(fake.serveHTTP))
+	t.Cleanup(func() {
+		fake.server.Close()
+		for _, request := range fake.snapshot() {
+			require.NotContains(t, []string{http.MethodDelete, http.MethodPut, http.MethodPatch}, request.Method,
+				"delegation must never modify or delete existing records")
+			require.Equal(t, "Bearer "+delegationToken, request.Authorization, "every request must authenticate")
+			require.Equal(t, delegationPath, request.Path)
+		}
+	})
+	return fake
+}
+
+func (f *fakeCloudflareAPI) snapshot() []fakeCloudflareRequest {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return append([]fakeCloudflareRequest(nil), f.requests...)
+}
+
+func (f *fakeCloudflareAPI) failedLabel() string {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return f.failedPostLabel
+}
+
+func (f *fakeCloudflareAPI) serveHTTP(w http.ResponseWriter, r *http.Request) {
+	request := fakeCloudflareRequest{
+		Method: r.Method, Path: r.URL.Path, Query: r.URL.Query(), Authorization: r.Header.Get("Authorization"),
+	}
+	var bodyError error
+	if r.Method == http.MethodPost {
+		bodyError = json.NewDecoder(r.Body).Decode(&request.Body)
+	}
+	f.mu.Lock()
+	f.requests = append(f.requests, request)
+	if r.Method == http.MethodPost {
+		f.postCount++
+	}
+	postPosition := f.postCount
+	f.mu.Unlock()
+	if bodyError != nil {
+		w.WriteHeader(http.StatusBadRequest)
+		return
+	}
+
+	if request.Authorization != "Bearer "+delegationToken {
+		w.WriteHeader(http.StatusForbidden)
+		return
+	}
+	if request.Path != delegationPath {
+		w.WriteHeader(http.StatusNotFound)
+		return
+	}
+	w.Header().Set("Content-Type", "application/json")
+	switch r.Method {
+	case http.MethodGet:
+		page := 1
+		if raw := request.Query.Get("page"); raw != "" {
+			var err error
+			page, err = strconv.Atoi(raw)
+			if err != nil || page < 1 {
+				w.WriteHeader(http.StatusBadRequest)
+				return
+			}
+		}
+		if page == f.listingFailPage {
+			w.WriteHeader(f.listingFailCode)
+			_, _ = w.Write([]byte(f.listingFailBody))
+			return
+		}
+		pageSize := 2 // Deliberately ignore per_page, type and name filters.
+		if f.pageSize > 0 {
+			pageSize = f.pageSize
+		}
+		start := min((page-1)*pageSize, len(f.records))
+		end := min(start+pageSize, len(f.records))
+		// Cloudflare reports total_pages 0 for an empty result set.
+		totalPages := (len(f.records) + pageSize - 1) / pageSize
+		if f.reportedTotalPages > 0 {
+			totalPages = f.reportedTotalPages
+		}
+		response := map[string]any{
+			"success": true, "errors": []any{}, "messages": []any{}, "result": f.records[start:end],
+		}
+		if !f.omitResultInfo {
+			response["result_info"] = map[string]int{"page": page, "per_page": pageSize, "count": end - start,
+				"total_count": len(f.records), "total_pages": totalPages}
+		}
+		_ = json.NewEncoder(w).Encode(response)
+	case http.MethodPost:
+		if postPosition == 2 && f.createFailBody != "" {
+			name, _ := request.Body["name"].(string)
+			f.mu.Lock()
+			f.failedPostLabel = strings.TrimSuffix(name, "."+delegationZoneRoot)
+			f.mu.Unlock()
+			w.WriteHeader(f.createFailCode)
+			_, _ = w.Write([]byte(f.createFailBody))
+			return
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"success": true, "errors": []any{}, "messages": []any{}, "result": request.Body,
+		})
+	default:
+		w.WriteHeader(http.StatusMethodNotAllowed)
+	}
+}
+
+func newTestReconciler(t *testing.T, fake *fakeCloudflareAPI, labels fakeLabelSource) (*Reconciler, *bytes.Buffer) {
+	t.Helper()
+	client, err := NewCloudflareClient(CloudflareOptions{
+		BaseURL: fake.server.URL + "/client/v4", Token: delegationToken, ZoneID: delegationZoneID,
+		HTTPClient: ap.NewGuardedHTTPClient(true, 5*time.Second),
+	})
+	require.NoError(t, err)
+	var log bytes.Buffer
+	reconciler, err := NewReconciler(Options{
+		Client: client, Labels: labels, ZoneRoot: delegationZoneRoot,
+		Nameservers: []string{"ns1.tdpl.example", "ns2.tdpl.example"},
+		Logger:      slog.New(slog.NewTextHandler(&log, &slog.HandlerOptions{Level: slog.LevelDebug})),
+	})
+	require.NoError(t, err)
+	return reconciler, &log
+}
+
+func requestsByMethod(requests []fakeCloudflareRequest, method string) []fakeCloudflareRequest {
+	var matching []fakeCloudflareRequest
+	for _, request := range requests {
+		if request.Method == method {
+			matching = append(matching, request)
+		}
+	}
+	return matching
+}
+
+func requireDelegationResult(t *testing.T, result Result, created, delegated, withoutLive []string, conflicts []Conflict, failed []Failure) {
+	t.Helper()
+	require.ElementsMatch(t, created, result.Created, "Created")
+	require.ElementsMatch(t, delegated, result.AlreadyDelegated, "AlreadyDelegated")
+	require.ElementsMatch(t, withoutLive, result.DelegatedWithoutLiveActors, "DelegatedWithoutLiveActors")
+	require.ElementsMatch(t, conflicts, result.Conflicting, "Conflicting")
+	require.ElementsMatch(t, failed, result.Failed, "Failed")
+}
+
+func TestReconcileCreatesMissingLiveDelegation(t *testing.T) {
+	fake := newFakeCloudflareAPI(t, nil)
+	r, _ := newTestReconciler(t, fake, fakeLabelSource{labels: []store.InstanceLabel{{Label: "a", HasLiveActor: true}}})
+	result, err := r.Reconcile(context.Background())
+	require.NoError(t, err)
+	requireDelegationResult(t, result, []string{"a"}, nil, nil, nil, nil)
+	posts := requestsByMethod(fake.snapshot(), http.MethodPost)
+	require.Len(t, posts, 1)
+	require.Equal(t, delegationPath, posts[0].Path)
+	require.Equal(t, "Bearer "+delegationToken, posts[0].Authorization)
+	require.Equal(t, map[string]any{"type": "NS", "name": "a.tdpl.example", "content": "ns1.tdpl.example", "ttl": float64(3600)}, posts[0].Body)
+	require.NotContains(t, posts[0].Body, "proxied")
+}
+
+func TestReconcileReadsAllPagesAndMatchesOnlyApexNS(t *testing.T) {
+	fake := newFakeCloudflareAPI(t, []fakeDNSRecord{
+		{Type: "NS", Name: "a.tdpl.example", Content: "NS1.tdpl.example."},
+		{Type: "NS", Name: "b.tdpl.example", Content: "ns2.tdpl.example"},
+		{Type: "NS", Name: "C.TDPL.example.", Content: "ns1.tdpl.example"},
+		{Type: "NS", Name: "x.a2.tdpl.example", Content: "ns1.tdpl.example"},
+		{Type: "A", Name: "d.tdpl.example", Content: "ns1.tdpl.example"},
+		{Type: "A", Name: "e.tdpl.example", Content: "192.0.2.2"},
+	})
+	r, _ := newTestReconciler(t, fake, fakeLabelSource{labels: []store.InstanceLabel{
+		{Label: "a", HasLiveActor: true}, {Label: "b", HasLiveActor: true},
+		{Label: "c", HasLiveActor: true}, {Label: "a2", HasLiveActor: true}, {Label: "d", HasLiveActor: true},
+	}})
+	result, err := r.Reconcile(context.Background())
+	require.NoError(t, err)
+	requireDelegationResult(t, result, []string{"a2", "d"}, []string{"a", "b", "c"}, nil, nil, nil)
+	requests := fake.snapshot()
+	var pages []int
+	for _, request := range requestsByMethod(requests, http.MethodGet) {
+		page := 1
+		if request.Query.Get("page") != "" {
+			parsedPage, parseErr := strconv.Atoi(request.Query.Get("page"))
+			require.NoError(t, parseErr)
+			page = parsedPage
+		}
+		pages = append(pages, page)
+	}
+	require.ElementsMatch(t, []int{1, 2, 3}, pages)
+	var postNames []string
+	for _, request := range requestsByMethod(requests, http.MethodPost) {
+		postNames = append(postNames, request.Body["name"].(string))
+	}
+	require.ElementsMatch(t, []string{"a2.tdpl.example", "d.tdpl.example"}, postNames)
+}
+
+func TestReconcileWarnsAndPreservesForeignDelegations(t *testing.T) {
+	for _, tc := range []struct {
+		name      string
+		records   []fakeDNSRecord
+		delegated []string
+	}{
+		{name: "foreign only", records: []fakeDNSRecord{{Type: "NS", Name: "conflicted.tdpl.example", Content: "other-provider.example"}}},
+		{name: "configured and foreign", records: []fakeDNSRecord{
+			{Type: "NS", Name: "conflicted.tdpl.example", Content: "ns1.tdpl.example"},
+			{Type: "NS", Name: "conflicted.tdpl.example", Content: "other-provider.example"},
+		}, delegated: []string{"conflicted"}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			fake := newFakeCloudflareAPI(t, tc.records)
+			r, log := newTestReconciler(t, fake, fakeLabelSource{labels: []store.InstanceLabel{{Label: "conflicted", HasLiveActor: true}}})
+			result, err := r.Reconcile(context.Background())
+			require.NoError(t, err)
+			requireDelegationResult(t, result, nil, tc.delegated, nil,
+				[]Conflict{{Label: "conflicted", Contents: []string{"other-provider.example"}}}, nil)
+			require.Contains(t, log.String(), "level=WARN")
+			require.Contains(t, log.String(), "conflicted")
+			require.Contains(t, log.String(), "other-provider.example")
+			requests := fake.snapshot()
+			require.NotEmpty(t, requests)
+			for _, request := range requests {
+				require.Equal(t, http.MethodGet, request.Method)
+			}
+		})
+	}
+}
+
+func TestReconcileCreatesOnlyForLiveActors(t *testing.T) {
+	fake := newFakeCloudflareAPI(t, nil)
+	r, _ := newTestReconciler(t, fake, fakeLabelSource{labels: []store.InstanceLabel{
+		{Label: "live1", HasLiveActor: true}, {Label: "dead1", HasLiveActor: false},
+	}})
+	result, err := r.Reconcile(context.Background())
+	require.NoError(t, err)
+	requireDelegationResult(t, result, []string{"live1"}, nil, nil, nil, nil)
+	posts := requestsByMethod(fake.snapshot(), http.MethodPost)
+	require.Len(t, posts, 1)
+	require.Equal(t, "live1.tdpl.example", posts[0].Body["name"])
+}
+
+func TestReconcileReportsDelegationsWithoutLiveActors(t *testing.T) {
+	fake := newFakeCloudflareAPI(t, []fakeDNSRecord{
+		{Type: "NS", Name: "gone.tdpl.example", Content: "ns1.tdpl.example"},
+		{Type: "NS", Name: "ghost.tdpl.example", Content: "ns2.tdpl.example"},
+		{Type: "NS", Name: "foreign.tdpl.example", Content: "other-provider.example"},
+	})
+	r, log := newTestReconciler(t, fake, fakeLabelSource{labels: []store.InstanceLabel{
+		{Label: "gone", HasLiveActor: false}, {Label: "foreign", HasLiveActor: false},
+	}})
+	result, err := r.Reconcile(context.Background())
+	require.NoError(t, err)
+	requireDelegationResult(t, result, nil, nil, []string{"gone", "ghost"},
+		[]Conflict{{Label: "foreign", Contents: []string{"other-provider.example"}}}, nil)
+	require.Contains(t, log.String(), "gone")
+	require.Contains(t, log.String(), "ghost")
+	require.Empty(t, requestsByMethod(fake.snapshot(), http.MethodPost))
+}
+
+func TestReconcileContinuesAfterSecondCreateFails(t *testing.T) {
+	for _, tc := range []struct {
+		name    string
+		status  int
+		message string
+	}{
+		{name: "HTTP 500", status: http.StatusInternalServerError, message: "cloudflare create temporarily unavailable"},
+		{name: "success false", status: http.StatusOK, message: "cloudflare NS record rejected"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			fake := newFakeCloudflareAPI(t, nil)
+			fake.createFailCode = tc.status
+			fake.createFailBody = fmt.Sprintf(`{"success":false,"errors":[{"code":81057,"message":%q}],"messages":[],"result":null}`, tc.message)
+			r, log := newTestReconciler(t, fake, fakeLabelSource{labels: []store.InstanceLabel{
+				{Label: "first", HasLiveActor: true}, {Label: "second", HasLiveActor: true},
+				{Label: "third", HasLiveActor: true},
+			}})
+			result, err := r.Reconcile(context.Background())
+			require.Error(t, err)
+			posts := requestsByMethod(fake.snapshot(), http.MethodPost)
+			require.Len(t, posts, 3)
+			failedLabel := fake.failedLabel()
+			require.NotEmpty(t, failedLabel)
+			require.Equal(t, strings.TrimSuffix(posts[1].Body["name"].(string), ".tdpl.example"), failedLabel)
+			var created []string
+			for _, label := range []string{"first", "second", "third"} {
+				if label != failedLabel {
+					created = append(created, label)
+				}
+			}
+			require.ElementsMatch(t, created, result.Created)
+			require.Empty(t, result.AlreadyDelegated)
+			require.Empty(t, result.Conflicting)
+			require.Empty(t, result.DelegatedWithoutLiveActors)
+			require.Len(t, result.Failed, 1)
+			require.Equal(t, failedLabel, result.Failed[0].Label)
+			require.Contains(t, result.Failed[0].Reason, tc.message)
+			require.NotContains(t, err.Error(), delegationToken)
+			require.NotContains(t, log.String(), delegationToken)
+		})
+	}
+}
+
+func TestReconcileAbortsBeforeCreatingOnListingFailure(t *testing.T) {
+	for _, tc := range []struct {
+		name   string
+		page   int
+		status int
+		body   string
+	}{
+		{name: "first page HTTP 500", page: 1, status: http.StatusInternalServerError,
+			body: `{"success":false,"errors":[{"code":1000,"message":"listing unavailable"}],"messages":[],"result":null}`},
+		{name: "second page success false", page: 2, status: http.StatusOK,
+			body: `{"success":false,"errors":[{"code":81057,"message":"listing refused on page two"}],"messages":[],"result":null}`},
+		{name: "first page malformed JSON", page: 1, status: http.StatusOK, body: `{not-json`},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			fake := newFakeCloudflareAPI(t, []fakeDNSRecord{
+				{Type: "A", Name: "one.tdpl.example", Content: "192.0.2.1"},
+				{Type: "A", Name: "two.tdpl.example", Content: "192.0.2.2"},
+				{Type: "A", Name: "three.tdpl.example", Content: "192.0.2.3"},
+			})
+			fake.listingFailPage, fake.listingFailCode, fake.listingFailBody = tc.page, tc.status, tc.body
+			r, log := newTestReconciler(t, fake, fakeLabelSource{labels: []store.InstanceLabel{{Label: "missing", HasLiveActor: true}}})
+			_, err := r.Reconcile(context.Background())
+			require.Error(t, err)
+			requests := fake.snapshot()
+			require.Empty(t, requestsByMethod(requests, http.MethodPost))
+			var pages []int
+			for _, request := range requestsByMethod(requests, http.MethodGet) {
+				page := 1
+				if request.Query.Get("page") != "" {
+					parsedPage, parseErr := strconv.Atoi(request.Query.Get("page"))
+					require.NoError(t, parseErr)
+					page = parsedPage
+				}
+				pages = append(pages, page)
+			}
+			if tc.page == 2 {
+				require.Contains(t, pages, 2)
+			}
+			require.NotContains(t, err.Error(), delegationToken)
+			require.NotContains(t, log.String(), delegationToken)
+		})
+	}
+}
+
+func TestReconcileAbortsWhenListingOmitsResultInfo(t *testing.T) {
+	var records []fakeDNSRecord
+	for index := range 100 {
+		records = append(records, fakeDNSRecord{Type: "NS", Name: fmt.Sprintf("filler%03d.tdpl.example", index), Content: "ns1.tdpl.example"})
+	}
+	records = append(records, fakeDNSRecord{Type: "NS", Name: "conflicted.tdpl.example", Content: "other-provider.example"})
+	fake := newFakeCloudflareAPI(t, records)
+	fake.pageSize = 100
+	fake.omitResultInfo = true
+	r, log := newTestReconciler(t, fake, fakeLabelSource{labels: []store.InstanceLabel{{Label: "conflicted", HasLiveActor: true}}})
+	_, err := r.Reconcile(context.Background())
+	require.Empty(t, requestsByMethod(fake.snapshot(), http.MethodPost))
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "result_info")
+	require.NotContains(t, err.Error(), delegationToken)
+	require.NotContains(t, log.String(), delegationToken)
+}
+
+func TestReconcileAbortsWhenListingExceedsPageCap(t *testing.T) {
+	// The listing cap is 100 pages of 100 records, well above the zone quota.
+	const listingPageCap = 100
+	fake := newFakeCloudflareAPI(t, nil)
+	fake.reportedTotalPages = listingPageCap + 1
+	r, log := newTestReconciler(t, fake, fakeLabelSource{labels: []store.InstanceLabel{{Label: "missing", HasLiveActor: true}}})
+	_, err := r.Reconcile(context.Background())
+	requests := fake.snapshot()
+	require.Empty(t, requestsByMethod(requests, http.MethodPost))
+	require.Len(t, requestsByMethod(requests, http.MethodGet), listingPageCap)
+	require.Error(t, err)
+	require.NotContains(t, err.Error(), delegationToken)
+	require.NotContains(t, log.String(), delegationToken)
+}
+
+func TestReconcileDoesNotClassifyLabelsWhenSourceFails(t *testing.T) {
+	fake := newFakeCloudflareAPI(t, []fakeDNSRecord{{Type: "NS", Name: "ghost.tdpl.example", Content: "ns1.tdpl.example"}})
+	r, _ := newTestReconciler(t, fake, fakeLabelSource{err: errors.New("label source unavailable")})
+	result, err := r.Reconcile(context.Background())
+	require.Error(t, err)
+	require.Empty(t, requestsByMethod(fake.snapshot(), http.MethodPost))
+	require.Empty(t, result.DelegatedWithoutLiveActors)
+}
diff --git a/internal/store/bridged_actors.go b/internal/store/bridged_actors.go
index 1e7965b..2ede1ba 100644
--- a/internal/store/bridged_actors.go
+++ b/internal/store/bridged_actors.go
@@ -5,6 +5,7 @@ import (
 	"database/sql"
 	stderrors "errors"
 	"fmt"
+	"strings"
 	"time"
 
 	"github.com/bluesky-social/indigo/atproto/syntax"
@@ -219,3 +220,34 @@ func scanBridgedActor(row rowScanner) (*BridgedActor, error) {
 	actor.ConsentState = ConsentState(consentState)
 	return &actor, nil
 }
+
+// ListInstanceLabels returns each instance label under zoneRoot and whether it
+// has at least one actor that has not been deleted.
+func (r *postgresBridgedActors) ListInstanceLabels(ctx context.Context, zoneRoot string) ([]InstanceLabel, error) {
+	root := strings.TrimSuffix(strings.ToLower(strings.TrimSpace(zoneRoot)), ".")
+	const query = `
+		SELECT split_part(lower(handle), '.', 2) AS label,
+		       bool_or(consent_state <> $2) AS has_live_actor
+		FROM bridged_actors
+		WHERE right(lower(handle), length($1) + 1) = '.' || $1
+		  AND cardinality(string_to_array(lower(handle), '.')) = cardinality(string_to_array($1, '.')) + 2
+		GROUP BY label
+		ORDER BY label`
+	rows, err := r.db.QueryContext(ctx, query, root, string(ConsentStateDeleted))
+	if err != nil {
+		return nil, fmt.Errorf("list instance labels under %q: %w", root, err)
+	}
+	defer rows.Close()
+	var labels []InstanceLabel
+	for rows.Next() {
+		var label InstanceLabel
+		if err := rows.Scan(&label.Label, &label.HasLiveActor); err != nil {
+			return nil, fmt.Errorf("scan instance label under %q: %w", root, err)
+		}
+		labels = append(labels, label)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("read instance labels under %q: %w", root, err)
+	}
+	return labels, nil
+}
diff --git a/internal/store/bridged_actors_test.go b/internal/store/bridged_actors_test.go
index ca5e3a3..78c78c4 100644
--- a/internal/store/bridged_actors_test.go
+++ b/internal/store/bridged_actors_test.go
@@ -2,6 +2,7 @@ package store
 
 import (
 	"context"
+	"fmt"
 	"testing"
 	"time"
 
@@ -306,3 +307,41 @@ func TestBridgedActors_HandleCollisionIsConflict(t *testing.T) {
 	_, err = repo.UpsertActor(ctx, noHandle)
 	assert.NoError(t, err, "actors without handles must not collide")
 }
+
+func TestBridgedActors_ListInstanceLabels(t *testing.T) {
+	repo := NewBridgedActors(testDB(t))
+	ctx := context.Background()
+	for index, fixture := range []struct {
+		handle  string
+		consent ConsentState
+	}{
+		{"alice.a.tdpl.example", ConsentStateOK},
+		{"bob.b.tdpl.example", ConsentStateDeleted},
+		{"carol.b.tdpl.example", ConsentStateDeleted},
+		{"dave.c.tdpl.example", ConsentStateDeleted},
+		{"eve.c.tdpl.example", ConsentStateOK},
+		{"frank.n.tdpl.example", ConsentStateNoBridge},
+		{"user.foreign.nottdpl.example", ConsentStateOK},
+		{"x.d.other.example", ConsentStateOK},
+	} {
+		actor := testActor()
+		actor.APActorID = fmt.Sprintf("https://lemmy.example/u/instance-label-%d", index)
+		actor.DID = fmt.Sprintf("did:plc:%024d", index+1)
+		actor.Handle = fixture.handle
+		actor.ConsentState = ConsentStateOK
+		_, err := repo.UpsertActor(ctx, actor)
+		require.NoError(t, err, "insert %s", fixture.handle)
+		if fixture.consent != ConsentStateOK {
+			require.NoError(t, repo.SetConsentState(ctx, actor.APActorID, fixture.consent))
+		}
+	}
+
+	labels, err := repo.ListInstanceLabels(ctx, "tdpl.example")
+	require.NoError(t, err)
+	assert.ElementsMatch(t, []InstanceLabel{
+		{Label: "a", HasLiveActor: true},
+		{Label: "b", HasLiveActor: false},
+		{Label: "c", HasLiveActor: true},
+		{Label: "n", HasLiveActor: true},
+	}, labels)
+}
diff --git a/internal/store/interfaces.go b/internal/store/interfaces.go
index 693d0e6..67ba04b 100644
--- a/internal/store/interfaces.go
+++ b/internal/store/interfaces.go
@@ -181,6 +181,10 @@ type BridgedActors interface {
 	// MarkProfileSynced records when the actor's profile record was last
 	// (re)materialized.
 	MarkProfileSynced(ctx context.Context, apActorID string, syncedAt time.Time) error
+
+	// ListInstanceLabels returns distinct second-label instances under zoneRoot,
+	// including labels whose actors are all deleted (HasLiveActor=false).
+	ListInstanceLabels(ctx context.Context, zoneRoot string) ([]InstanceLabel, error)
 }
 
 // APActors persists the ActivityPub identities Coves users get on the user
diff --git a/internal/store/models.go b/internal/store/models.go
index 822f90d..a9d87c4 100644
--- a/internal/store/models.go
+++ b/internal/store/models.go
@@ -520,3 +520,10 @@ type OutboundDelivery struct {
 	CreatedAt       time.Time
 	UpdatedAt       time.Time
 }
+
+// InstanceLabel describes a bridged instance's DNS label and whether at least
+// one of its actors has not been deleted.
+type InstanceLabel struct {
+	Label        string
+	HasLiveActor bool
+}
-- 
2.51.2