Cluster registration: the four paths, the two primitives, and what is already built
Status: open design. One slice is built (§7); the other registration paths are design.
Origin. The owner, 2026-08-17:
“you register your cluster, you don’t provide a license on the cluster. is dns sufficient way to register it or not? like didn’t we originally have you just pop in the dns of the cluster?”
and, on how it should feel:
- deploy the cluster → log in as master → a Register button in the console that does some kind of SSO-ish thing with the portal
- terraform-deployed → simply registered at deployment
- you already have a cluster → go to the portal and register it there
- portal deploys it → registered on deployment
and the ruling that shapes the data model:
“registration is a separate concept from entitlement. entitlements are based on registration, but you register regardless of if you have entitlements or licenses.”
1. The short answer to the DNS question
Section titled “1. The short answer to the DNS question”Yes, and we already built it, twice, and one of the two answers is better than the question implies.
“Didn’t we originally have you just pop in the DNS of the cluster?” We did,
and it still works. shc license activate with no arguments is exactly that:
the estate names its own serving domain, the broker proves the estate controls
that domain, and the estate pulls a signed licence. No key, no account, no
portal. That is POST /activate, live today.
But the framing to correct is DNS as an identifier versus DNS as a proof, because they are different jobs and we answered them separately:
| Question | Answer today | Where |
|---|---|---|
| Who is this cluster, across time? | a durable opaque registration (reg_…), NOT the domain | license-broker/brokerd/registration.go |
| May this box receive a licence for this name, right now? | domain-proof: authoritative DNS + an IP-pinned dial + a nonce echo | license-broker/brokerd/callback.go |
So: DNS alone is not sufficient as an authenticator, and we never shipped it
as one. The instinct that “anyone can point a name at anything” is right, and
the compensating control is already the one the coordinator guessed:
essentially ACME’s: the broker issues a nonce, the cluster serves it at
/.well-known/shc-license-challenge on the registered name, the broker fetches
it. Ruling R3 (2026-07-29) says so in as many words: “DNS control is the
proof, exactly as ACME HTTP-01 validates over plain HTTP to issue
certificates.”
Two details worth knowing, because they are stronger than a naive HTTP-01:
- The A/AAAA answer is read from the domain’s own nameservers, never a
recursive cache, and the callback dial is pinned to that address so
nothing re-resolves in between. RFC1918 / loopback / link-local targets are
refused (
X403032LICDNS). - There is deliberately no certificate leg. Retired at R3, because it bought nothing over DNS control and blocked estates whose TLS was not yet up.
And DNS is already not the primary key. The 2026-08-16 ruling (“let’s just
go straight through the registration approach then instead of domains”) is
implemented: the rights record’s identity is a registration, the domain is an
attribute of it, and a domain CHANGE is already handled with a dual-domain
transition file and a 35-day window (metaKeyDomainPrev /
domainTransitionWindow). The GitLab-transfer failure mode the coordinator
raised (a name silently disappearing) is the exact event that seam exists to
survive.
The real gap is none of the above. It is:
First contact for a cluster the callback cannot reach.
A CI estate on 10.0.0.0/8 serving at shc.test has no publicly-delegated name
and no routable address, and never will; .test is reserved by RFC 2606 and
is guaranteed never to be delegated. Same for an airgapped customer. Until this
week the only answer for both was the vendor mints a file offline with the
founder signing seed and a human carries it over, which is what §7 replaces.
2. The four paths are two primitives
Section titled “2. The four paths are two primitives”The owner named four registration paths. They are two mechanisms, and the coordinator’s read of that is correct:
Primitive A: interactive claim (paths 1 and 3)
Section titled “Primitive A: interactive claim (paths 1 and 3)”One cluster, one human, one approval. Paths 1 and 3 are the same exchange run in opposite directions:
- Path 1 (console Register button): the OAuth 2.0 device authorization grant (RFC 8628). The cluster asks the portal for a device code, the console shows the user code and a link, the human approves in the portal where they are already signed in, the cluster polls and receives its credential.
- Path 3 (portal-first): the inverse: the portal mints a claim code and
the human pastes it into the cluster (
shc register <code>).
Device flow is the right shape for path 1 for a reason that is structural, not stylistic: the cluster’s Keycloak realm and the portal’s realm are different realms. Device flow never asks the cluster to authenticate the human; it asks the human to authenticate to the portal on their own device, and hands the cluster only the outcome. Nothing has to federate.
We already ship the path-3 half in another subsystem: shc portal register <code> (modules/portal/). Entitlement should reuse its shape rather than coin
a second one.
Primitive B: account-scoped provisioning credential (paths 2 and 4)
Section titled “Primitive B: account-scoped provisioning credential (paths 2 and 4)”Many clusters, no human, one credential held by an automation:
- Path 2: terraform holds it and registers each estate it creates.
- Path 4: the portal’s own provisioner holds it and does the same.
The credential must be account-scoped, not per-cluster: it registers N clusters and each registration gets its own durable identity. A per-cluster secret would need a human to mint one per cluster, which is path 1 with extra steps.
Both primitives must terminate in the same place: the cluster ends up holding a stable, revocable, broker-issued registration. Everything after that (entitlement lookup, refresh, transfer, revocation) is one code path.
3. Registration ≠ entitlement: what the data model becomes
Section titled “3. Registration ≠ entitlement: what the data model becomes”The owner’s ruling makes registration free, frictionless and universal, and entitlement a separate record hanging off it. Concretely:
Account└── Registration reg_…, durable, opaque, allocated once ├── labels display name, the cluster's domain(s) ← DNS lives HERE ├── credential revocable, rotatable, what the cluster holds └── Entitlement 0..1 active ├── tier free | hobby | pro | enterprise | trial | ci-test ├── caps max_nodes, max_cores, … ├── term granted_at, expires_at ← trial expires SERVER-SIDE └── invoice link the audit chain back to the moneyFour consequences worth stating because they are the point of the split:
- A registered, unentitled cluster is a first-class state. The portal’s “my clusters” lists it, shows unlicensed, and offers an upgrade. Today an unlicensed estate is invisible to us; we have no inventory at all.
- Registration yields the things that are not entitlement: inventory, a support channel, upgrade notifications, security advisories, and a place to attach an entitlement later. None of those should cost money and all of them are currently unavailable to the free tier.
- A trial stops being a file carried onto a box. It becomes an entitlement granted to a registration, expiring server-side. That is strictly better than a local 30-day timer: it cannot be reset by reinstalling, it is visible in the portal, and “has this customer already trialled?” becomes answerable.
- The domain stays in the signed file regardless. This is the one place the split must NOT be taken further, and decision §2.2 already ruled it: the binding an offline verifier can evaluate is a domain compare. A registration credential proves we issued something; it proves nothing to a daemon with no network. So the file keeps naming domains even though the ledger is keyed on the registration.
4. What already exists vs. what is new
Section titled “4. What already exists vs. what is new”| Piece | State |
|---|---|
Domain-proof activation (POST /activate) | built, live |
Re-fetch with prior proof (POST /refresh) | built, live |
| Durable registration as record identity | built (registration.go), plus a POST /backfill-registrations migration |
| Domain change → dual-domain transition file + 35-day window | built |
domains field on a live record | built and load-bearing: it is enforced at verify time (VerifyForDomain), not merely recorded: a file whose domains do not include the estate’s SHC_HOST is refused X403030LICDOM |
Portal claim-code registration (shc portal register <code>) | built, for the portal/marketplace, NOT wired to entitlement |
| Registration for a cluster the callback cannot reach | NEW, built this lane (§7) |
| Device-authorization flow (path 1) | not built |
| Account-scoped multi-cluster provisioning credential (paths 2 and 4, general form) | not built; §7 ships the narrow, test-scoped version |
| Entitlement as a record keyed on registration, separate from the licence file | not built; Keygen is still keyed on metadata.domain at the wire level |
| Portal “my clusters” with entitlement state | not built |
The honest summary: the hard cryptographic half is done and the product half is not. What is missing is mostly portal surface and one identity table, not protocol.
5. The three things the design needs that were not named
Section titled “5. The three things the design needs that were not named”5.1 Air-gapped / offline registration
Section titled “5.1 Air-gapped / offline registration”Many self-hosters have no outbound internet by policy, and retrofitting this is painful, so the shape should be fixed now even if it is built later.
Recommended shape: request blob → response blob. The cluster emits a signed, self-describing request; a human moves it across the gap by any means; the portal returns a response blob; the cluster ingests it.
shc register --offline > request.json # {registration_request, domain, nodes, nonce, pubkey}# … carry request.json out, upload to the portal, download response.json …shc register --offline-response response.jsonProperties that matter:
- The request carries a cluster-generated keypair, so the response can be encrypted to it and a stolen response blob is useless elsewhere.
- The response carries both the registration identity and the entitlement, so one round trip suffices.
- Renewal is the same two files again. An airgapped estate should be handed a
long term (the
perpetualFile/ rolling-file distinction of R18 already exists) so this is annual, not weekly. - It must be usable by a human with a USB stick and no CLI on the other side; so the blobs are base64 text, and the portal accepts a paste box, not only a file upload.
This is deliberately NOT POST /mint with a vendor token, which is what
airgapped delivery uses today. That path makes the vendor type the customer’s
identity in by hand, which §2.3 of the licensing decision already names as the
thing that gives airgapped clusters “an identity that is free text a vendor
typed”.
5.2 Transfer, re-registration, and conflict
Section titled “5.2 Transfer, re-registration, and conflict”Three distinct events that must not be conflated:
| Event | Correct behaviour |
|---|---|
| Cluster rebuilt with the same name/domain, no state | It is a NEW registration. The old one goes stale and is reaped or shown as inactive. Never silently adopt; “the same name” is not identity. |
| Cluster re-registering with its existing credential | Idempotent. Same registration, refreshed credential if asked. |
| Registering something already claimed by another account | Explicit refusal with a path forward, never a silent overwrite: “This cluster is already registered to another account. Ask its owner to release it, or contact support.” |
| Transfer between accounts | A deliberate two-sided action: the current owner releases (or approves), the new owner claims. Never a one-sided claim, or a leaked code becomes a theft primitive. |
The anti-double-grant invariant already implemented for /record (the lookup
ladder registration → domain → prev-domain → only then create) is the same
shape this needs, and the same reasoning applies: a record is never created
while a record for that identity exists.
One trap to avoid: making the refusal say “no purchase on record”. That is
X403035LICGRT, it means something else, and pointing a paying customer at the
shop because their cluster is claimed elsewhere is the worst possible message.
5.3 Revocation
Section titled “5.3 Revocation”Two directions, and the second one is the one that gets forgotten:
Vendor → cluster. Decommissioning: the portal revokes the registration. The cluster discovers it at its next check.
What the cluster does when revoked, and this is a product ruling, not an implementation detail: degrade to unregistered, never break. Specifically:
- Running deployments keep running. Working auth stays connected. No data is lost. The daemon still starts. This is the existing no-rug/no-brick guarantee and revocation must not become a back door around it.
- The estate stops receiving entitlement refreshes and falls to the free tier posture at its own expiry, through the ordinary lapse path with its ordinary grace period.
- The operator is TOLD, in the banner channel that survives the launcher being disabled.
A revocation that bricks an estate is a support incident, not an enforcement mechanism, and for a product holding customer backups and a vault, it is the single most damaging thing we could build.
6. UX for path 1, since the owner asked for great UX
Section titled “6. UX for path 1, since the owner asked for great UX”The gesture to copy is gh auth login / Tailscale, and it is:
- An unregistered cluster’s console shows a banner: “This cluster isn’t registered · Register”.
- Pressing it opens the portal with the code already embedded in the URL, so the human APPROVES rather than types. The code is still displayed, for the case where the browser is on another machine.
- The console keeps polling. When the credential lands, the banner clears itself: no refresh, no “click here when you’re done”.
- If the human abandons it, the code expires quietly and the banner returns to its resting state. No error.
The details that make it feel finished rather than functional: the user code is
short and unambiguous (no 0/O, no 1/l); the portal page names the
cluster being claimed (domain + node count) so the human can tell they are
approving the right thing; and after approval the portal says “You can close
this” rather than leaving a dead tab.
7. What is built and verified this lane
Section titled “7. What is built and verified this lane”The smallest honest slice: primitive B, scoped to clusters that cannot answer a domain callback, which is exactly path 2, and which unblocks the test tier.
Broker: POST /register (license-broker/brokerd/enrollment.go). Armed by
its own LB_ENROLL_CODE, separately from LB_VENDOR_TOKEN, and scoped so
that holding the code is worth as little as possible:
- reserved-TLD domains only (
.test/.invalid/.localhost, RFC 2606; names the public DNS can never delegate, so a licence issued here can never reach a real estate); - 3 nodes, ceilinged at 5 in code;
- 7 days, ceilinged in code so the env can only shorten it;
- Pro codes, never Enterprise: no
TENANCY,SUPPORT,CUSTOM_IMAGESorWHITE_LABEL; - watermarked, so a leaked file announces itself;
- touches Keygen not at all; it is not a weaker
/record, it cannot reach/record, and that is asserted by a test.
It returns {license, registration}: the entitlement AND the durable identity,
kept separable on the wire so the §3 model can land without a format change.
Estate: shc license register <code> (modules/license/cluster_register.go,
POST /api/method/shc.license.register). The cluster registers ITSELF and pulls;
nothing is hand-carried. Everything after the exchange (supersession refusal,
store, publish, reverify) is shared with the domain-callback path, so an estate
cannot tell how its file arrived. The code may be read from stdin (-), and
every automated caller uses that form.
Terraform: shc_license (terraform/provider/internal/provider/license_resource.go).
Entitlement becomes a node in the graph:
shc_cluster → shc_node.bootstrap → shc_license → shc_node.workers.
This is what removes the two-phase -target apply the harness had grown.
Verification. TestEnrollmentLoopEndToEnd runs the real broker in
production callback posture (no dev relaxation of any kind; enrollment has
no callback to relax) against a real license.Service, and asserts the estate
ends up keyed, holding a registration, entitled to clustering, capped at 3
nodes, and NOT entitled to TENANCY. A live 3-node Proxmox estate provisioned
from empty is the second proof.
What CI holds, and its blast radius. One enrollment code. It cannot reach
/mint, /record or /sync; it cannot mint for any delegable domain; the
worst it can produce is a 3-node, 7-day, watermarked, Pro-capped licence bound
to a name no public estate can serve at. Rotation is one env var on the
broker (LB_ENROLL_CODE) plus the CI variable; unsetting it removes the route
entirely (404, not 401). Outstanding files expire within 7 days on their own.
The signing seed is nowhere in this loop, which was the point.
8. What I recommend the owner rule on
Section titled “8. What I recommend the owner rule on”- Adopt registration-as-identity with entitlement as a separate record (§3). The seam exists; the table does not.
- Build primitive A as OAuth device flow (§2), and let path 3 be the same exchange in reverse rather than a second mechanism.
- Generalise primitive B from the test-scoped code shipped here to a real account-scoped provisioning credential, same route, different scope resolution.
- Fix the offline shape now (§5.1) even if it is built later.
- Rule that revocation degrades and never bricks (§5.3).
None of these requires moving a tier line, and this note deliberately proposes
none. The trial remains Hobby / max_nodes = 1 as ruled on 2026-08-16; §3.3
notes only that a server-side trial makes that ruling easier to administer,
not that it should change.