DNS-domain licensing: the signed token IS the licence, 2026-08-21
Status: OWNER-RULED, ADVERSARIALLY REVIEWED, AMENDED, MERGED. The first cut was reviewed and found to have a hole big enough to void the feature’s whole purpose (§3.1). The cert proof that closes it is the amendment; the review’s other findings are folded in below and marked.
The ruling, in one line: licensing is domain-bound. The vendor mints one signed token per customer domain; the customer publishes it as a TXT record in their own zone; the estate reads its own record and is licensed. There is no licence key to type and no post-deployment registration step.
1. What changed, and what did not
Section titled “1. What changed, and what did not”Nothing about the licence FORMAT changed, and that is the whole design. SHC
has exactly one licence token: shclic.v1.<payload>.<signature>, Ed25519
over the payload bytes, domain-bound by the payload’s own domains field
(modules/license/format.go, unchanged since the CE/EE split). What this
change adds is a second carrier for those identical bytes:
| carrier | how the estate gets it | when you use it |
|---|---|---|
| DNS record (primary) | the estate resolves _shc-license.<its own domain> | the ordinary path; the zone is already in your terraform |
| installed token (fallback) | shc license install <token> | a domain whose zone you do not control, a lab name, a bring-up before DNS exists, the unbound vendor fleet blanket |
Both take the same value. shc license mint --dns prints it as a record;
shc license install takes it as an argument. An operator can copy a value
straight out of dig into the install verb and it works.
2. Why this removes the registration step
Section titled “2. Why this removes the registration step”The terraform that stands an estate up already owns the zone. So the same
apply that creates the cluster can create the record that licenses it:
module "cluster" { source = ".../terraform/modules/shc/hetzner" license_dns_token = var.license_dns_token # from the vendor, once bootstrap = { host = "cloud.acme.com", … }}
resource "hetznerdns_record" "licence" { # your provider, your zone count = module.cluster.license_dns_record.enabled ? 1 : 0 zone_id = data.hetznerdns_zone.main.id name = module.cluster.license_dns_record.zone_relative_name type = "TXT" ttl = module.cluster.license_dns_record.record_ttl value = module.cluster.license_dns_record.record_value_quoted}The vendor mints once per customer domain. The customer sets one variable. Nobody runs a verb on the estate, ever.
3. Why the signature, and not DNSSEC, and why that was not enough
Section titled “3. Why the signature, and not DNSSEC, and why that was not enough”The record is public and world-readable. Anybody can read castclaws.com’s licence record and paste it into bitspur.com’s zone.
That copy fails, offline, on a laptop, with the network unplugged. The vendor
signature covers the licensed domain, so a token published at the wrong
name is a valid signature over the wrong name, and
Verifier.VerifyForDomain refuses it against the domain the estate actually
serves. Nothing in this scheme trusts DNS to tell the truth; DNS is only
asked where the bytes are, never whether they are genuine.
Consequences worth stating plainly, because they are what make the scheme cheap:
- No DNSSEC dependency. A spoofed answer can only deliver a token that either fails the signature check or is bound to some other domain.
- No resolver pinning. The estate uses whatever resolver it already has.
- Works airgapped. The estate resolves its OWN domain, so an airgapped
site’s own authoritative server answers and the query never leaves the
site. This is also why
license.offline(R21, “make zero outbound licensing attempts”) deliberately does not suppress the lookup: that policy is about not phoning the vendor, and this query does not. The kill switch for the lookup itself islicense.dns_enabled.
3.1 THE HOLE THE REVIEW FOUND, and the cert proof that closes it
Section titled “3.1 THE HOLE THE REVIEW FOUND, and the cert proof that closes it”Everything above defends exactly one attack (copy castclaws.com’s record into bitspur.com’s zone), and that is not the attack anyone would run. The real one never touches a zone:
dig +short TXT _shc-license.castclaws.com # the record is publicSHC_HOST=castclaws.com # you assert your own domainThe token is genuine, unexpired, and bound to castclaws.com; the estate says it serves castclaws.com; the signature verifies. Keyed, with the victim’s entitlements. No forgery, no vendor call, nothing detectable offline. The first cut shipped this, and the review demonstrated it empirically.
The root cause is structural: publishing the token made public a value that had never been public, while the only thing standing between that value and a licence was a string the operator asserts about themselves. Domain-binding is an honour system when the domain is public and the token is public.
The proof: possession of a publicly-trusted certificate for the licensed domain. An honest estate already holds one; SHC provisions it over ACME as a matter of course, so nothing is asked of the customer. A pirate cannot get one, because a public CA will not issue for a domain they do not control. The certificate is therefore a proof of domain control that is free for the honest party and fatal to the attack.
Four things are checked (modules/license/dns_cert.go), and each earns its
place:
| check | why |
|---|---|
chains to a public root, against a bare x509.SystemCertPool() | the daemon has pool-augmenting helpers (keycloak_trust, edge_ca_pool) and either would make the check pass on exactly the estates it must fail; an estate can mint itself a leaf for any name |
SAN covers the domain, via x509.Verify’s DNSName | applies the normal wildcard rules, so a *.acme.com estate proves cloud.acme.com; a hostname-keyed map would miss it, and wildcard issuance is a supported posture |
currently valid, via CurrentTime | an expired certificate is not a present-tense proof |
ExtKeyUsageServerAuth | an unrelated client or e-mail leaf carrying the name cannot stand in |
It must be LOCAL POSSESSION, not a dial. The cheap version (open a TLS
connection to the licensed domain and inspect the certificate) is worthless
and looks equivalent, which is why it is called out here. Dialling
castclaws.com:443 reaches the victim’s server, which of course presents a
good certificate; the pirate passes. What has to be proven is that this
estate holds the material, so the check reads chains off this node’s own
disk (traefik’s ACME store, plus certbroker’s delivered fullchain.pem) and
verifies them.
An unwired prover REFUSES. “The check is not installed” must not be a way past the check, or an attacker’s first move is to arrange for it to be missing. Nodes that genuinely cannot read the store (swarm, non-ingress, pre-ACME) do not honour a DNS licence directly; they receive the estate’s licence the way they always have.
It never bricks. A failed proof means the DNS licence is not honoured and
the estate falls through to whatever installed or broker licence it holds,
exactly as if no record existed. The operator gets X403044LICCRT in
shc license status naming which proof is missing: no certificate at all, a
certificate for another name, or one from a private/staging CA are three
different sentences because they have three different fixes.
3.2 THE CARRIER SPLIT, and why the file path is exempt
Section titled “3.2 THE CARRIER SPLIT, and why the file path is exempt”| DNS carrier | file install | |
|---|---|---|
| token published? | yes, world-readable in the zone | no, never leaves the estate |
| cert proof | REQUIRED | not required |
unbound token (* / empty) | REFUSED (§3.3) | accepted |
| audience | internet-facing estates | airgap, lab, vendor fleet, zones you do not control |
The exemption is not a concession, it is the same reasoning applied to a different fact pattern. There is nothing to harvest from an installed token, so there is no attack to close, and requiring a public certificate would break the deployment the file carrier exists for, since an airgapped estate has no public certificate by definition. The asymmetry tracks publication, which is the thing that actually changed.
3.3 Unbound tokens are refused from DNS (review finding F2)
Section titled “3.3 Unbound tokens are refused from DNS (review finding F2)”An unbound licence (empty domains, or a sole "*") matches every domain
by construction. That is right for the vendor fleet blanket installed on the
vendor’s own machines and catastrophic in a public record: one leaked blanket
would self-license any estate at any domain, straight past the domain match
the whole carrier rests on. mint --dns already refused to emit one; that
guard only binds the vendor’s own tooling, so the read path refuses one
too, on both the live and cached legs (X403043LICUNB). install still
accepts them; see the split above.
4. The account binding lives in the ledger, not the estate
Section titled “4. The account binding lives in the ledger, not the estate”The token carries an optional account field: the vendor ledger subject the
grant was sold to. It is display and support correlation only; nothing in
the binary gates on it, exactly as nothing gates on type.
That is deliberate. An estate can only ever answer three questions: is this token signed by a key I trust, is it for my domain, and is it in date. Questions about the commercial relationship (is this account in good standing, how many concurrent domains has it been sold) are answered where the vendor mints, because that is the only place with the facts. Putting a domain count in the token would be an unverifiable claim the estate has no way to check and every incentive to ignore.
Adding the field did not bump FormatVersion, and that is not an
oversight of the rule in license.go. The rule exists because the
signature covers the payload BYTES, so a change that altered those bytes for
an existing licence would invalidate it. omitempty is what makes this
change not that: a licence minted without an account marshals
byte-identically to before the field existed, so every licence in the field
keeps verifying. In the other direction decodePayload’s decoder ignores
unknown keys, so an older binary reads a token carrying one and simply does
not see it, correct behaviour for a field nothing gates on. A bump would
have refused every licence already issued.
5. Precedence: the strongest valid token wins
Section titled “5. Precedence: the strongest valid token wins”An estate may hold both an installed token and a licence record. The rule is not carrier-based:
The estate runs the STRONGER of the two, by the supersession ladder two licence files already use: later expiry wins; a perpetual beats a dated one; an equal term is broken by the later mint instant; an exact tie is broken only by granting strictly more.
strongerLicence is literally newerLicense || richerSameTerm, the
existing functions, not a reimplementation. A carrier-based rule (“DNS always
wins”, “the file always wins”) would be a second ordering to keep in sync
with the first, and would make one carrier a downgrade attack on the other.
shc license status reports which carrier is in force as source: dns /
source: file.
6. What DNS is not allowed to do: take a licence away
Section titled “6. What DNS is not allowed to do: take a licence away”A resolver outage, a registrar migration or a mistyped zone edit must never
unlicense a running estate. So the last token that resolved and verified
is cached on disk (license-dns.json, beside the licence token) and keeps
resolving. The cache is bounded two ways and both bounds matter:
- The token’s own expiry, which degrades the estate exactly as an expired file does: growth refused, running workloads untouched, renewal wording intact, 14-day grace before the strong lock. No brick.
DNSGraceDuration(14 days, the same constant as the lapse grace) since the last successful resolution, after which the cached copy stops being honoured at all.
Bound (2) is what keeps the carrier honest. Without it, a token that resolved once would license the estate until its expiry no matter what the zone said afterwards; “remove the record” would mean nothing.
Two failure directions are deliberate and worth naming:
- A token that fails signature or domain verification is never cached. A forgery must not earn a grace window.
- A record that is found and refused leaves an operator-facing note
(
X403042LICZON, surfaced inshc license status). The commonest field failure here is silent by construction (a record pasted from another estate’s zone, or a truncated value), and an estate that is quietly unlicensed for no visible reason is the worst outcome available.
6.1 Two clock-rollback holes, found by the tests
Section titled “6.1 Two clock-rollback holes, found by the tests”Both bounds above are measured as now - <recorded instant>, and both were
initially wrong in the same way: the subtraction goes negative when the
clock moves backwards, a negative age is trivially “fresh”, and the check can
then never be crossed. Winding a clock forward once and back again would have
pinned the memo and made the cache permanent.
- The memo now falls through when the age is negative; a clock that moved backwards is precisely when a re-resolve is wanted.
- The cache re-stamps a future
resolved_atto now and persists it. Clamping the age to zero was tried first and has the identical defect: the stamp never moves, so every later pass recomputes a negative age and clamps again. Re-stamping restarts the fourteen days from the correction, so a legitimate clock fix costs at most one extra window and the trick costs one window per rollback rather than an unbounded extension.
Anyone who can set the estate’s clock is root on the box and could patch the
binary, so the bar here is “not free”, not “impossible”. Pinned by
TestDNSCacheGraceSurvivesAClockRollback.
6.2 The Keycloak SPI reads a mirror (review finding F3)
Section titled “6.2 The Keycloak SPI reads a mirror (review finding F3)”The SPI is the estate’s other licence consumer and the first cut left it out
of the design entirely. It reads license.lic + estate-domain.json from the
mounted licence directory and has no DNS rung, and cannot cheaply have one,
since it would need the resolver, the supersession ladder and the certificate
proof, in Java, on a separate release clock. On an estate keyed only by its
record the SPI read nothing, resolved INDETERMINATE, and applied the free
seat cap while the daemon was happily keyed. That is daemon-vs-SPI
disagreement about one licence (the exact class of bug the estate-domain
materialisation was built to end), and it would have surfaced as Keycloak
quietly dropping to free limits weeks after a working install.
So a DNS-licensed daemon mirrors the token into the installed slot
(materialiseDNSForSPI), refreshed on every Reverify from the live answer.
Three properties make the mirror safe rather than a second grant:
- It never outlives its record. The moment the DNS carrier stops producing a licence (record withdrawn, grace bound closed, proof failed) the mirror is deleted on the same pass.
- It never touches an operator’s file. Deletion happens only when the bytes in the slot are byte-identical to the token this node recorded as its own mirror (in the DNS cache sidecar, so it survives restarts).
- It is never published to the replicated row. The row is the estate’s durable “we hold this licence” and every node materialises from it, so a mirror pushed there would turn a deleted TXT record into a permanent grant across the cluster.
status still reports source: dns. The mirror is a rendering of the
record, not a carrier, and calling it file would hide that removing the
record ends the licence.
6.3 Delink releases the estate; only removing the record releases the grant
Section titled “6.3 Delink releases the estate; only removing the record releases the grant”shc license delink drops the local files, tombstones the replicated row
and drops the cached DNS token; leaving the cache would make delink a lie
for up to the full grace window.
It deliberately does not stop the record from re-licensing the estate on
the next resolve, and it must not pretend to. The zone is the customer’s and
the record is the grant: an estate whose zone still says “licensed” is
licensed, and a local veto over a signed grant would be a second source of
truth in the one place licensing must not have one. So the CLI says so; a
delink that leaves the estate keyed by DNS prints the record name and tells
the operator to remove it. Pinned by TestDelinkDropsTheCachedDNSLicence and
TestDelinkWithTheRecordStillPublishedReLicenses.
6.4 Revocation is expiry
Section titled “6.4 Revocation is expiry”Offline verification and revocation lists are mutually exclusive; pubkey.go
already says the same thing about key rotation. A DNS-carried licence is
revoked the way every licence in this product is revoked: it runs out. What
DNS adds is that the vendor can decline to mint the next one and the
customer’s own zone stops carrying the old one, so the practical revocation
lever is the term length and terms should be sized accordingly. This is not
a weakening; it is the same lever a file licence has, plus one.
7. Why terraform computes the record but does not create it
Section titled “7. Why terraform computes the record but does not create it”modules/license-dns emits the record (name, type, TTL, whole value, 255-byte
chunks, zone-file line) and creates nothing. Three reasons, the first being
the load-bearing one:
- The licence carrier must not be the licensed daemon’s to delete. SHC
has a managed-DNS path (
shc_dns_record, served by the daemon’s own DNS module) and routing the licence record through it would look natural. That module owns what it creates: companion ownership TXT rows, sweeps at managed hosts, an orphan reaper. Putting the licence inside that blast radius means a daemon bug, a release retry or a teardown can remove the record that licenses it, and the failure surfaces a fortnight later as an estate that lapsed for no visible reason. Separation of duties: the operator’s IaC writes it, the daemon only ever reads it. shc_dns_recordcannot express it anyway; it classifiestargetinto A / AAAA / CNAME and has no TXT on the surface.- A zone is often not the cluster module’s to touch, and hard-wiring one cloud’s DNS provider would be wrong for every estate whose zone lives elsewhere and unusable for the airgapped case.
The module therefore declares no providers, so it composes with hetznerdns, cloudflare, aws, google, azurerm or plain RFC2136.
license_dns_token also installs the token via shc_license, and the
redundancy is deliberate: worker joins cannot wait on a DNS TTL, because
clustering is Pro-and-up and an unentitled join is refused X403029LICENT.
Installing puts the entitlement on the graph edge where it is needed; the
record is what keeps renewing afterwards without another apply. Same bytes,
so they cannot disagree.
8. Deprecation posture for the older registration paths
Section titled “8. Deprecation posture for the older registration paths”Per the ruling, no other registration mechanisms, but documented, not deleted:
| path | status | why it is still here |
|---|---|---|
shc license activate --broker / ActivateOnline + the /.well-known/shc-license-challenge endpoint | superseded; help text says so | in-flight estates registered this way; the challenge endpoint exists only to serve that callback and deprecates with it |
shc license register <code> | superseded; help text says so | its case (private-network, lab, airgapped) is exactly what the record serves better, but an enrollment code that stops being redeemable strands a customer mid-provision |
shc license refresh / MaybeRefresh (broker re-fetch) | KEPT, not registration | this is renewal delivery. A DNS-carried licence renews by the record changing, but an estate registered through the broker still renews by asking it. Retiring the verbs above must follow the estates, not lead them |
shc license activate <file> | kept, aliased | install is the better spelling and takes a bare token; activate stays for compatibility |
Nothing new should be built on the superseded paths. They come out once the registered population is migrated to records.
9. Open policy question (deliberately not decided here)
Section titled “9. Open policy question (deliberately not decided here)”Concurrent domains per purchase. The token binds one domain (or several,
if minted so). How many concurrent domains a single purchase may carry, and
whether a customer may move a licence between domains without a re-mint, is a
LEDGER policy: the estate cannot verify it and must not try. It is recorded
here as open rather than answered by implementation. activation_limit
already exists in the payload and is advisory in the offline binary.
10. Where it lives
Section titled “10. Where it lives”| what | where |
|---|---|
| the DNS rung, cache, grace, precedence | modules/license/dns.go |
| wired into the posture rebuild | modules/license/service.go (Reverify) |
| carrier provenance | modules/license/resolver.go (Source) |
| security corpus | modules/license/dns_test.go, dns_mint_test.go |
| vendor mint mode | modules/license/mint_cmd.go (--dns, --account) |
| fallback carrier verb | modules/license/commands.go (install) |
| kill switch | license.dns_enabled (config_keys.go, wired in daemon/wiring/license_wire.go) |
| record computation | terraform/modules/license-dns/ |
| the terraform variable | license_dns_token on modules/core and modules/shc/hetzner |
11. What the adversarial review found, and where each finding landed
Section titled “11. What the adversarial review found, and where each finding landed”| # | finding | disposition |
|---|---|---|
| F1 | HIGH: a public token + an operator-asserted domain + no proof of control = universal freeload (the pirate points SHC_HOST at the victim’s domain) | FIXED: the cert proof, §3.1. Pinned by TestPirateAtVictimDomainIsRefused / TestHonestEstatePassesWithItsOwnCert |
| F2 | an unbound token is a skeleton key and nothing on the read side refused one | FIXED: §3.3, X403043LICUNB, refused on both legs; install still accepts (TestDNSRefusesAnUnboundToken, TestInstallStillAcceptsAnUnboundToken) |
| F3 | a DNS-only estate silently unlicenses Keycloak (the SPI has no DNS rung) | FIXED: the SPI mirror, §6.2 (TestDNSLicenceIsMirroredForTheSPI, TestTheMirrorIsRemovedWhenTheRecordGoes, TestTheMirrorNeverOverwritesAnInstalledLicence) |
| F4 | the memo was not domain-keyed, so a live domain change served a licence resolved for the old one | FIXED: memo keyed on the normalised domain |
| F5 | ”the spent cache is DELETED” was unproven; removing the delete left the suite green | FIXED: the grace test now stats the file |
| F6 | sanitizeTXTValue could be replaced with the identity function | FIXED: TestSanitizeTXTValueStripsZoneToolingNoise + an end-to-end quoted-record case |
| F7 | ”strongest record wins” passed with a “last wins” mutant | FIXED: the rotation test runs both RR orders |
| F8 | ~18 pre-existing tests silently began making real LookupTXT calls | FIXED: package TestMain installs a refusing default resolver through one seam (defaultTXTLookup) |
| F9 | two tests asserted only “not keyed” and would pass with the carrier disabled | FIXED: both gained positive controls |
The review also recorded a proof of absence for chunk-rejoin ambiguity, multi-record downgrade, forged signatures, unknown-key injection, row/file isolation, clock rollback, and the terraform surface. Those arguments still hold and were not disturbed by this amendment.
12. Review checklist for whoever takes §0
Section titled “12. Review checklist for whoever takes §0”- The domain wall:
dns_test.go:TestDNSTokenForAnotherDomainRefusedis the castclaws-token-on-bitspur case. Confirm nothing downstream of it can adopt a token whosedomainsdo not cover the estate. - The cache: confirm nothing writes
license-dns.jsonbeforeVerifyForDomainreturns nil error. - The grace bound: confirm a spent cache is deleted rather than merely ignored, so it cannot be resurrected by a clock change.
- Isolation: confirm the DNS token never reaches the replicated licence row
(
TestDNSTokenIsNeverPublishedToTheEstateRow) nor the installed-file slot. - The
Accountfield: confirm the no-bump reasoning in §4 againstformat.go, and that no gate reads it. - The memo: confirm
dnsResolveIntervalactually bounds gate-miss lookups (TestDNSLookupIsNotRepeatedOnEveryResolve), sinceReverifyis on the gate-miss path. - The clock bounds (§6.1): both were wrong on the first pass and only one test
caught them. Look for any OTHER
now.Sub(...)in this feature that decides whether something is still valid. - The cert proof is the load-bearing wall now. Confirm the trust pool is the bare system pool at every call site, that no path can reach a passing verdict with an unwired prover, and that the proof gates the DNS carrier ONLY; an installed or broker licence must be unaffected by it.
- The mirror. Confirm it cannot outlive its record, cannot overwrite a file this node did not write, and never reaches the replicated row.