Skip to content
SHC Docs

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:

  1. deploy the cluster → log in as master → a Register button in the console that does some kind of SSO-ish thing with the portal
  2. terraform-deployed → simply registered at deployment
  3. you already have a cluster → go to the portal and register it there
  4. 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.”


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:

QuestionAnswer todayWhere
Who is this cluster, across time?a durable opaque registration (reg_…), NOT the domainlicense-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 echolicense-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.


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 money

Four consequences worth stating because they are the point of the split:

  1. 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.
  2. 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.
  3. 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.
  4. 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.

PieceState
Domain-proof activation (POST /activate)built, live
Re-fetch with prior proof (POST /refresh)built, live
Durable registration as record identitybuilt (registration.go), plus a POST /backfill-registrations migration
Domain change → dual-domain transition file + 35-day windowbuilt
domains field on a live recordbuilt 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 reachNEW, 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 filenot built; Keygen is still keyed on metadata.domain at the wire level
Portal “my clusters” with entitlement statenot 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”

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.

Terminal window
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.json

Properties 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:

EventCorrect behaviour
Cluster rebuilt with the same name/domain, no stateIt 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 credentialIdempotent. Same registration, refreshed credential if asked.
Registering something already claimed by another accountExplicit 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 accountsA 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.

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:

  1. An unregistered cluster’s console shows a banner: “This cluster isn’t registered · Register”.
  2. 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.
  3. The console keeps polling. When the credential lands, the banner clears itself: no refresh, no “click here when you’re done”.
  4. 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.


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_IMAGES or WHITE_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.


  1. Adopt registration-as-identity with entitlement as a separate record (§3). The seam exists; the table does not.
  2. Build primitive A as OAuth device flow (§2), and let path 3 be the same exchange in reverse rather than a second mechanism.
  3. Generalise primitive B from the test-scoped code shipped here to a real account-scoped provisioning credential, same route, different scope resolution.
  4. Fix the offline shape now (§5.1) even if it is built later.
  5. 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.