Skip to content
SHC Docs

shc dns: the verb gap-inventory G33/G43/G51 asks for, and why it was not built

Status: open design. §6.2 is built. §6.1, §6.3 and §6.4 are still open. Verified against ce main 638e16b and shc main 91eec3a3e on 2026-08-07. Every claim below is a reading of code in those two trees; no estate was contacted.

★ Owner ruling, 2026-08-07: §6.2 is yes, detect-only. In the owner’s words: “Have it read the DNS with SHC doctor, I guess, but it wouldn’t fix it… a check that can’t fix something doesn’t really hurt.”

Built as dns.record-ownership (ce modules/dns/doctor.go + modules/dns/audit.go). No CLI subtree, no new namespace, no record CRUD, no prescription; the registry entry carries Name and Build only, and both repos pin that: ce’s modules/dns/doctor_test.go asserts the entry has no Prescribe/BuildPrescribe, and shc’s tests/unit/modules/dns/audit_test.go proves the no-write property at the provider boundary over a fixture containing the one claim a reap apply would rewrite. §6.1 is therefore untouched: the removal still stands, and nothing here reverses it.

The check goes further than a bare surfacing of POST /api/dns/reap, because that route only answers half the question. A read-only audit mode adds one zone-wide enumeration of the managed types per zone, which is what makes the other half answerable: a claim standing next to no record (the host is dark), a host we intend to publish that somebody else claims (every sync is skipped, X403040DNSOWN), and a host we intend to publish whose records carry no claim at all (delete refuses it, X403041DNSUNO, so it outlives the deployment). §7 lists what landed.

G43/G51 are NOT closed and §3’s fork is untouched; see §6.3/§6.4.

The question in one line: shc dns is not missing; it was built, shipped, and deliberately deleted by owner ruling, and the repo carries a regression test whose only job is to keep it deleted. G33/G43/G51 are real operator pain, but closing them the way the gap inventory proposes means reversing that ruling. §6 asks which of four dispositions you want.


1. The premise that sent me here, and why it does not survive contact

Section titled “1. The premise that sent me here, and why it does not survive contact”

The task I was given stated the key insight as already established:

This is a missing SURFACE, not a missing capability. SHC already holds the DNS credential and already writes the host A record plus its heritage=shc TXT marker. modules/dns/commands/ simply does not exist. So the work is exposing what the daemon can already do.

One third of that is true. The credential half is exactly right; the DNS token root-fix put shc_connection at system scope, and the estate’s hcloud connection really does manage bitspur.com, flyingfoxlabs.in and selfhostedcloud.org. SHC can reach the zone.

The other two thirds do not hold.

1.1 modules/dns/commands/ does not “simply not exist”; it was removed

Section titled “1.1 modules/dns/commands/ does not “simply not exist”; it was removed”

Superset commit 28a52fb2140abc5d74b1b0c38c6602a1c462faa6 (2026-07-10):

feat(cli)!: remove shc dns + shc rollback; records are lifecycle-managed, restore covers rollback

A feat!: breaking change, deleting a working shc dns record tree with ls / get / create / rm verbs. Three artifacts keep it dead, all live in the trees named above:

modules/dns/register.go carries the ruling as its module comment:

// The DNS module deliberately registers NO CLI subtree: DNS is
// transparent product behaviour; records flow from the deployment
// lifecycle (`--host`, `--dns-provider`, install/uninstall) and the
// provider-side ladder, never from operator record CRUD. The /api/dns
// routes stay for the daemon's own lifecycle path and machine callers
// (terraform's shc_dns_record over UDS/HTTP).

modules/dns/router.go:59, independently, in the route table:

// ... There is deliberately NO `shc dns` CLI
// over these routes; records are lifecycle-managed (--host); the
// surface serves the daemon itself and machine callers (terraform's
// shc_dns_record) over the UDS ...

tests/unit/cli/cli_test.go:91: a pin test that fails the build if the verb returns:

var removedTopLevelCommands = []string{
"app", "audit", "dns", "docker", "extract", "info",
"metrics", "network", "ps", "rollback",
}
func TestBuild_RemovedCommandsStayRemoved(t *testing.T) { … }

expectedTopLevelCommands in the same file adds the plain-English form: “docker / network / metrics / dns intentionally have NO CLI surface.” And scripts/arch-fitness.sh check 14 records the collateral: “Floor history: 21 → 20 when shc dns (record create + its Example) was deliberately removed with the whole command tree (28a52fb21).”

Building the verb therefore is not filling a hole. It is deleting a regression test written to prevent exactly this, deleting two comments that state the ruling, and reverting a breaking-change commit. That is resolving an owner ruling by implementation, so this document exists instead.

1.2 The daemon cannot write the records G43 actually wants

Section titled “1.2 The daemon cannot write the records G43 actually wants”

G43’s missing set is MX, SPF, DMARC, and mailcow’s DKIM TXT. SHC has no code path that can express any of them. Measured in ce 638e16b:

  • Service.ResolveTarget is the only record-type selector on the write path. It returns A, AAAA or CNAME and nothing else: IP literal, IP literal, or name.
  • CreateRecordForHost takes a bare target string and routes through it.
  • SyncRecordsForHost takes a typed []TargetSpec, so an MX can be passed, and it is collected into the desired map and then silently dropped, because the reconcile loop that follows visits only {RecordTypeA, RecordTypeAAAA, RecordTypeCNAME}.
  • That same hard-coded triple appears in five loops across service.go and reap.go. It is the managed set.
  • RecordTypeMX / RecordTypeNS exist so the Provider boundary can carry back a zone walk. No service-level writer reaches them.
  • The intent model has no room for one either: IngressHost is {Host, Service, Path, Port}, host_mapping has no record-type column, and ManagedDNSHostnames returns bare hostnames.

So publishing mail DNS is new capability, not new surface. This is now recorded, with a build-derived guard, in docs/architecture/cluster/dns-provider-sync.md.

1.3 The proposal I was handed as settled was written by an agent

Section titled “1.3 The proposal I was handed as settled was written by an agent”

The gap inventory’s line:

An shc dns record verb over the connection it already owns would close G33 and G43 together.

comes from docs/handoff/2026-08-05-sso-certs-and-the-gap-inventory.md, whose G33/G43/G51 text lands in commits trailed Co-Authored-By: Claude Opus 5 (branch docs/gap-inventory, e.g. 05f3b08b0, 8bad897e8, 3ef99e26b). It is an agent’s recommendation recorded in a handoff, and it reads as a finding because handoffs do not distinguish measurement from proposal.

Against it stand a dated owner quote from the 2026-07-14 estate review, “No direct dns control”, a feat!: commit, two code comments, and a pin test. An agent’s recommendation does not outrank an owner ruling, and the ordering here is not close.


2. Five independent restatements of the same policy

Section titled “2. Five independent restatements of the same policy”

Worth listing because they were written by different hands at different times and none of them cites the others:

#WhereWhat it says
1Owner, 2026-07-14 estate review”No direct dns control”
2modules/dns/register.go”records flow from the deployment lifecycle … never from operator record CRUD”
3modules/dns/router.go:59”deliberately NO shc dns CLI over these routes”
4apps/mailcow/mailcow-provision-smtp.job.yaml”SHC does not manage the mail domain’s DNS zone; publishing is the operator’s step”
5apps/mailcow/README.md §2”DNS: none of this is created by SHC”

mailcow’s README §1 draws the line the whole question turns on:

examplewhat it is
mail hostmail.corp.bitspur.comwhere the server listens, --host. SHC registers this A record.
mail domainbitspur.comwhat appears after the @, vars.mailDomain. SHC touches none of its records.

G43 is entirely about the second row.


3. ★ The hazard that makes this a real fork, not a formality

Section titled “3. ★ The hazard that makes this a real fork, not a formality”

The obvious implementation, publish MX/SPF/DMARC/DKIM and stamp them heritage=shc like every other managed record, arms the reaper against an estate’s mail routing.

reap.go’s safety argument is that it “never looks at a record it did not provably write”: its candidate set is exactly the hosts carrying this cluster’s ownership TXT. The file names the protected class explicitly, twice: “the apex, mail/MX, SPF/DKIM/DMARC TXT” and “Anything without an shc ownership TXT (the apex, MX/SPF/DKIM/DMARC)”. Mail records are safe from the sweeps because they are unclaimed.

Stamping them changes that in one step. ManagedDNSHostnames, the desired-host set the reaper reconciles against, is built from ingress intents and returns bare hostnames. A _dmarc.bitspur.com or a dkim._domainkey.bitspur.com is not an ingress host and never will be, so a claimed mail record is orphan-shaped by construction: owned by this cluster, named by nothing. The next reap pass deletes it. Inbound mail then fails silently and totally, and the sweep that did it is the one that has already leaked in production (the 2026-07-31 cross-provider sweep found 44 stale heritage=shc records, two resolving to IPs the cloud had recycled to third parties).

There is an existing exemption, and it has the opposite failure mode. CreateRecordForHost mints a pinned TXT (shc/pinned=1); reap.go:656 keeps pinned claims and never deletes them. Pinning mail records would stop the reaper eating them, and would mean they survive uninstall and estate destroy, which is the subdomain-takeover finding, aimed at the records carrying an organisation’s mail identity.

So mail DNS forces a choice between two failure modes, and that choice, not the CLI ergonomics, is the actual decision:

dispositionreap behaviourfailure mode
claimed, unpinnedswept when not in the desired setdeletes live MX/DKIM
claimed, pinnednever sweptoutlives the estate (takeover class)
unclaimed (today)invisibleoperator publishes by hand (G43/G51)

A fourth cell, claimed, pinned, and released by name at uninstall, is buildable, but it needs the desired-set model to grow a record-type dimension it does not have (§1.2), and it needs a rule for a mail domain shared by several stacks.


4. What each gap actually needs: they do not need the same thing

Section titled “4. What each gap actually needs: they do not need the same thing”

G33: “no way to ask SHC what DNS records it owns.” This is a read. It creates nothing, claims nothing, and strengthens the ownership marker the doctrine exists to protect. The engine already exists and is already exposed: POST /api/dns/reap is a faithful dry run by default, enumerates every zone cluster-wide, and reports Owned / Kept / Pinned / Unadopted / Candidates / ZoneErrors. That route postdates the 2026-07-10 removal; it is the one piece of this surface the ruling never considered. shc doctor today carries zero DNS probes, so nothing surfaces orphans to an operator at all, which is the operator-facing half of the active security finding.

G43 / G51: publishing mail DNS. New capability, plus the §3 ownership decision, plus an app.yaml schema that does not exist (no app in the catalogue declares any DNS need; ce has no parser for one).

Collapsing these three into one verb is what makes the ask look bigger than it is. G33 is cheap and nearly doctrine-neutral; G43/G51 are neither.


Two findings worth having before anything is designed.

The value is already in the platform’s hands. mailcow-provision-smtp.job.yaml step 6 reads the key back from mailcow’s API into $DKIM_TXT and then only echos it, with the §2 comment attached. Hooks run as sandboxed one-off containers with no daemon reachability, no UDS mount, no token, no shc binary, so a hook cannot publish a record even in principle. But the stdout marker channel already exists: ::shc-hook:var:<key>=<value>:: and ::shc-hook:secret:… are parsed by RunHookActionList and persisted by PersistHookMintedVars. A hook can already hand a runtime-discovered DKIM key back to the platform. Nothing consumes it as a record; that is the whole missing link, and it is small.

The 255-byte problem the README warns about is already solved. README §2 cautions that a ~392-character DKIM value exceeds the single-string TXT limit and that “a provider that silently truncates instead of chunking will leave you with a syntactically valid, permanently broken DKIM record.” dnsapi.EncodeTXT already splits payloads into ≤255-octet strings before escaping, precisely so a chunk boundary cannot cut an escape sequence, and Route 53 / Hetzner / PowerDNS all consume it. Whatever publishes DKIM inherits correct chunking for free.

Also: any record this grows must follow the function-not-product host rule (knowledge., not affine.). For mail that is already how it reads: mail., dkim._domainkey., _dmarc. are all functional names.


6.1: Does the 2026-07-10 removal of shc dns still stand? If yes, G33/G43/G51 stay open by design and the gap inventory should be annotated to say so rather than continuing to list them as unbuilt work. If no, say so explicitly, because reversing it means editing removedTopLevelCommands, both code comments, and the arch-fitness floor.

6.2: May G33 be closed without reopening the verb? ★ ANSWERED: yes, detect-only. BUILT. The shape is a shc doctor diagnosis over the existing sweep: read-only, no new namespace, no record CRUD, and it puts the 44-orphan class in front of an operator for the first time. It contradicts none of the five statements in §2, all of which are about mutation. See the status block at the top of this document and §7.

6.3: Should SHC ever own mail DNS, and under which cell of the §3 table? This is the real fork. “Never; mail domains stay operator-owned” is a coherent answer and matches every artifact in §2; it just means G43/G51 close as won’t-fix and the README stays the deliverable.

6.4: If mail DNS is in scope, does it arrive declaratively? The doctrine-shaped version is an app.yaml block that mailcow authors and the install pipeline publishes alongside CreateDeploymentDNSRecords, records deriving from platform intent, which is what “no direct DNS control” asks for. The imperative shc dns record create version is the one that contradicts it. These are different products; only the first can be built without reversing 6.1.


Still no verb and no CLI. In ce:

  • modules/dns/audit.go: Service.InspectOwnedRecords, a strictly read-only census. It runs through the SAME reapWithKeep core the sweeps do (the connection walk, the cross-tenant provider resolution, the inline-provider arm), so it cannot go blind to a wiring the reaper can see; inline.go is exactly that lesson, a whole enumeration arm both sweeps had never walked. Its one addition is a zone-wide enumeration of {A, AAAA, CNAME} per zone, paid only on this pass; ReapOrphanRecords and ReleaseOwnedRecords are behaviourally and byte-for-byte unchanged, which TestAuditLeavesTheReapReportAlone pins.
  • modules/dns/reap.go: ReapReport gains four audit-only fields (Audited, Claims, ForeignHosts, UnclaimedHosts) and reapOpts an audit flag. Nothing else in the file changed behaviour: the flag never travels with apply, and every delete gate, the pinned exemption and the blast-radius guard are untouched.
  • modules/dns/doctor.go: the dns.record-ownership diagnosis and its renderer. No Prescribe, no BuildPrescribe, and every hint that names a live-zone mutation leads with the word MUTATES.
  • modules/dns/register.go: registered through registry.DiagnosesWithDeps, which adds a diagnosis, not a command; the module’s “no CLI subtree” comment now says why the read is allowed to live there.
  • modules/dns/doctor_test.go: the detect-only pin (the app.integration-drift shape), the render states, the tier discipline, and the probe-separator trap.

In shc: tests/unit/modules/dns/audit_test.go: the behavioural half, including the no-write proof measured at the provider boundary over a fixture that deliberately contains a predecessor claim on an intended host, which is the row a reap apply rewrites. Docs in docs/reference/cli/doctor.md#dns-record-ownership and docs/architecture/cluster/dns-provider-sync.md.

7.2 What was landed alongside this document originally

Section titled “7.2 What was landed alongside this document originally”

One commit on docs/dns-record-scope-and-verb-question:

  • docs/architecture/cluster/dns-provider-sync.md gains the measured record-type scope: the managed set is {A, AAAA, CNAME}, mail DNS is outside it by design, and why that invisibility is load-bearing.
  • tests/unit/modules/dns/doc_traefik_env_test.go gains three assertions that derive the claim from the ce build pinned in go.mod rather than restating it: the Target→Record Type table matches ResolveTarget, ResolveTarget yields nothing outside that table, and MX/NS stay unreachable from the selector. Proven to go red by corrupting the table before landing.

The point of the guard is that the next reader measures §1.2 instead of re-deriving it, and that a ce pin bump which does widen the managed set surfaces here, where §3’s ownership question is written down, rather than in production.