Marketplace identity and install: RULED 2026-08-16
Status: RULED. Of the four questions this document opened, THREE ARE NOW CLOSED (Q1, Q2, Q3; see §10); ONE REMAINS OPEN (Q4). This records the owner design conversation of 2026-08-16, which until now lived only in a chat transcript. Everything in §1–§8 is settled. §10 carries each question’s disposition inline: a closed question keeps its original framing so the reasoning that closed it is legible against the alternatives it beat.
Amended 2026-08-16 (later the same day) with the owner’s follow-up
rulings: Q2 ruled YES (free installs require a portal account), which closes
Q3 by construction; Q1 closed by
2026-08-16-portal-cluster-identity.md
Ruling 1.
Companions:
../proposals/2026-08-14-marketplace-architecture.md
·
../proposals/2026-08-14-portal-architecture.md
·
2026-08-16-marketplace-entitlement-and-licensing.md:
the licensing half: what a paid install adds to the existing broker→Keygen
substrate, the domain-proof vs cluster-registration identity seam, and the
approval/spending-limit state machine that sits in front of a purchase.
This document answers the question those two left open: who is logged in
where, and how does a click in a cluster console become an install.
The model in one paragraph
Section titled “The model in one paragraph”Three separate populations touch the store, and they are deliberately not merged. Purchases are owned by central accounts; installs are performed by cluster tenant users on their own realm credentials; and entitlement rides the cluster, not the person. Federation runs one way only: our IdP into a customer’s master realm, never the reverse. The console does not embed the store; it links out in a new tab carrying a short-lived assertion the target cluster’s own daemon minted, which is both how the store learns where to install and why a stolen link cannot be aimed anywhere else.
1. Three populations, deliberately not merged (ruled)
Section titled “1. Three populations, deliberately not merged (ruled)”| population | authenticates against | what they can do |
|---|---|---|
| (a) anonymous visitors | nothing | browse the public store |
| (b) central portal/marketplace accounts | our Keycloak (my. / marketplace.) | own purchases |
| (c) cluster tenant users | their own cluster’s realm | do installs |
(a) is not a concession, it is a requirement. The store must serve unauthenticated browsers for SEO; a crawler has no account. Anything that put a login in front of the catalogue would take the storefront off the index.
(b) is already ruled, in the marketplace architecture §2: “accounts own purchases; the portal claims them onto registered clusters.” This document does not reopen it.
(c) is the new half. A tenant manager installing an app authenticates to their own cluster, with credentials their own organisation issued. They do not need, and by default do not have, an account in our store.
(Scope note, added with the Q2 ruling: that sentence is about installing
from the cluster, shc install, the console. An install initiated at
the marketplace does require a portal account, free or paid, because the
store has no other way to learn which cluster to install onto. See §10 Q2.)
2. Entitlement follows the CLUSTER, not the person (ruled)
Section titled “2. Entitlement follows the CLUSTER, not the person (ruled)”A tenant manager may install a paid app because their cluster is entitled (its domain sits in the right Keygen tier), not because they personally hold a marketplace account.
This is the load-bearing consequence of §1, and it is what makes the three-population split work at all: without it, (c) collapses into (b) and we would have to register every customer employee in our store in order for any of them to install anything. That is an absurd requirement to place on a customer, and a customer-data liability we have no reason to accept.
It also composes cleanly with what already exists: the domain-bound broker
machinery (license-broker → Keygen → shclic.v1) is already a statement
about a cluster, not about a person. Entitlement-follows-the-cluster is not
a new mechanism, it is naming the one we built.
3. Federation is ONE-WAY, and stays that way (ruled)
Section titled “3. Federation is ONE-WAY, and stays that way (ruled)”Already ruled in the portal architecture §2: the portal’s vendor IdP federates into a cluster’s master realm.
The reverse is REFUSED. A cluster realm authenticating into our store is not on the table, now or later. The reason is a trust boundary, not a preference:
customer realms are customer-controlled.
A customer admin owns their Keycloak completely. If their realm could assert identity into our store, that admin could mint themselves accounts in our store, or, worse, because it is quieter, mint themselves claims: entitlements, tier membership, purchase ownership. There is no hardening that fixes this, because the attacker is the legitimate administrator of the asserting IdP. The only correct answer is that the arrow never points that direction.
This is why §1 and §2 are shaped the way they are. Because we will not accept customer-realm assertions, cluster users cannot be store users, so entitlement must ride the cluster.
4. No iframe, and the second reason (ruled twice, reason recorded)
Section titled “4. No iframe, and the second reason (ruled twice, reason recorded)”Already ruled: “it comes from marketplace.selfhostedcloud.org not an iframe. it opens in a new tab like everything else” (marketplace §1), and “consoles are linked out in new tabs, never embedded” (portal §4).
The owner deliberately pressure-tested this ruling rather than accepting it, and asked that the practical reason be written down alongside the architectural one. It is:
An iframe of the central store inside a cluster console is a THIRD-PARTY
CONTEXT. The console is served from the customer’s own domain; the store is
marketplace.selfhostedcloud.org. In that frame the store’s cookies are
third-party cookies:
- Safari blocks them outright (ITP), and has for years.
- Chrome is closing the same door.
So the iframe cannot hold a session, not “degrades”, cannot. The embedded store would be permanently logged out for a large fraction of users with no action they could take.
The workarounds make it worse, not better. CHIPS (partitioned cookies) and the Storage Access API both exist, and both put a tracking-style consent prompt in front of the user, a browser-chrome dialogue asking whether this site may track them across sites. Asking a customer’s staff to grant cross-site tracking permission to their vendor, inside their own admin console, in order to see an app catalogue, is a worse product than a link.
The no-iframe ruling therefore survives contact with the pressure test on two independent grounds: the architectural one (cluster credentials never enter the store) and this one (the browser will not let the embed work anyway).
5. The new-tab signed handoff (ruled): the mechanism that replaces the iframe
Section titled “5. The new-tab signed handoff (ruled): the mechanism that replaces the iframe”The console links out to the store, and the link carries an assertion:
- minted on demand by the DAEMON, not pre-issued, not long-lived, not stored;
- signed with the cluster REGISTRATION credential, which we issue at portal registration, so we can verify it and the customer cannot forge it;
- short-lived;
- single-use / nonced;
- bound to the cluster id.
What this buys, in order:
- First-party context, so cookies work: the user lands on
marketplace.selfhostedcloud.orgas a top-level navigation. §4’s problem evaporates. - The store authenticates the USER normally: its own login, its own session, its own account model. The assertion is not a user credential and is never treated as one.
- The store learns WHICH CLUSTER from the assertion. This is the quiet win: it solves “how does the store know where to install” without a cluster picker. The user arrived from a cluster; the store knows which one; there is no dropdown to get wrong.
★ Read (3) as a convenience, not as the identity mechanism: this is the Q2 ruling (§10) applied back to this section. The assertion skips the cluster picker for a user who arrived from a console. It is not how the store learns who you are or which clusters you own: that is your portal account with its linked clusters, always, and it has to be, because a visitor arriving directly from search carries no assertion at all. The picker is the fallback path, not the exception. Nothing in §6 changes; the anti-replay property was always about which cluster may be targeted, never about who the user is.
6. The anti-replay property (ruled): the security core
Section titled “6. The anti-replay property (ruled): the security core”This is the part that makes §5 more than a convenience.
The assertion is minted BY THE TARGET CLUSTER. Therefore holding one is proof that you were already inside that cluster with the rights to ask for it. It is not a bearer token that grants access to a cluster; it is evidence of access you already had.
The consequence: it cannot be pointed at a cluster you lack access to. There is no cluster id you can substitute, because the signature is over the cluster id and the signing key is that cluster’s registration credential. The only cluster you can produce an assertion for is one that already let you in.
Belt and braces: the DAEMON IS THE FINAL AUTHORITY. The daemon honours an inbound install dispatch only if it matches a pending request it minted. So the failure mode of a stolen assertion is not “install on someone else’s cluster”; it is that the dispatch lands on a cluster that never asked, and is refused. Two independent mechanisms have to fail before anything installs anywhere.
7. Repo ruling: CLI yes, marketplace no (ruled)
Section titled “7. Repo ruling: CLI yes, marketplace no (ruled)”Users may add their own repos via the CLI. They may not add them via the marketplace.
The store shows the SHC-controlled catalogue only. Two reasons, both about a surface we control:
- No third-party content rendering in a surface we control. Whatever
appears on
marketplace.selfhostedcloud.orgis something we published. - No moderation surface we did not ask for. The moment arbitrary repos render in our storefront, we own takedowns, abuse reports, trademark complaints and content policy for other people’s content, a whole operational function acquired by accident.
The CLI is the right home for it precisely because it is the customer’s own surface, invoked by the customer, rendering nothing of ours.
8. Precedent: this shape exists in the world (recorded)
Section titled “8. Precedent: this shape exists in the world (recorded)”The owner asked whether any precedent exists. It does, and this is load-bearing for reviewers: the model in §1–§6 is not novel, and a reviewer who finds it strange is looking at a shape three large vendors already ship.
| precedent | how it maps |
|---|---|
| GitHub Apps / Marketplace (closest) | An app installs onto an org/repo, not onto a user. The installation has its own identity (an installation access token) distinct from the user who clicked. GitHub records who installed it. |
| Android Enterprise / managed Google Play | The enrollment token is our assertion: minted by the managed estate, presented to the central catalogue, binds the device to the org. |
| Apple Business Manager + MDM | The org buys; the MDM assigns to DEVICES; the end user needs no personal Apple ID at all. |
All three share the same four properties as our model: a central catalogue; many customer-controlled endpoints; purchase separated from installation; and machine identity distinct from human identity.
GitHub is the closest because it is the only one that also solves §9; see below.
9. OWED FIX CLOSED 2026-08-18: SHC now records WHO INSTALLED
Section titled “9. OWED FIX CLOSED 2026-08-18: SHC now records WHO INSTALLED”✅ LANDED as ce!114 (ce/migrations/20260818140325_installed_by.sql).
The gap below was real and is now closed; the shape it left unspecified is
recorded at the end of this section, because “the owner did not specify the
column, the table, or the shape” was the whole of what was owed.
The original finding, kept verbatim; it is the evidence the fix was needed, and a closed gap whose evidence is deleted becomes a claim.
Verified by content on 2026-08-16 against ce. This is a real gap, not a suspicion:
ce/ent/schema/deployment.go: the deployment row carriestenant_name,app_name,app_version,app_digest,environment,recorded_node_id,pinned_node_id,status, runtime/placement/storage columns, timestamps. There is no installer,installed_by,created_by,ownerorrequested_bycolumn.git grepover ce for those names returns nothing outside unrelated words (“installer” as inInstallerFunc), and no migration ince/migrations/ever added one.ce/ent/schema/vdeployment.go: same story, no installer field.- The audit and events_log tables do carry an
actorcolumn (ce/ent/schema/audit.go,ce/ent/schema/events_log.go), hash-chained in audit’s case. But actor defaults to the literal"shc"(modules/audit/service.godefaultActor,modules/events/service.go), and every producer found in the tree sets it to a process name:"vault","health.poll_nodes","health.poll_deployments". Nothing on the install path sets it to a human. So the column exists and is unused for this purpose; it is a place to put the answer, not the answer.
Why this matters here. §1–§6 build a model in which apps have owners. That phrase means nothing if the system cannot say who installed a thing. An audit trail is table stakes; it is the difference between a design and a claim. GitHub records who installed, which is exactly what makes its installation-identity model legible to the org that owns the repo.
This is recorded as owed work, not as a ruling: the owner did not specify
the column, the table, or the shape. The minimum honest statement is that the
gap is real and the model above assumes it will be closed.
9.1 THE SHAPE, as landed (ce!114, 2026-08-18)
Section titled “9.1 THE SHAPE, as landed (ce!114, 2026-08-18)”The owner’s later instruction, land every remaining schema change before the flatten, is the ruling that unblocked this. What follows is what was built, stated so that a reader of this document does not have to read ce to know what the column means.
| question | answer |
|---|---|
| which table(s) | BOTH: deployment and vdeployment. This section named both, and a vdeployment IS an install: shc install nginx-a/mysite is a thing an operator did that provisioned a bucket, a database and a realm. It is a resolve-half fact, so it does not breach the run-half exclusion vdeployment is built around. |
| what it holds | a closed <kind>:<id> grammar (ce/core/actor), not a free string: user:<sub>@<realm>, local:, portal:[<account>]. |
| nullable | yes, and NULL means THE ROW PREDATES THE COLUMN, nothing else. |
| indexed | no. Nothing selects, filters or joins on it; the read arrives with the row. |
| backfilled | no, deliberately; see below. |
The sub, not a username. A durable column carrying a display name starts
lying the first time somebody edits their profile. The realm qualifies it
because a sub is unique only inside its realm, which is precisely the point
of §1’s three-population split. The same reasoning already governs
wire.Requester.Ref: “an opaque, cluster-minted handle … stable per user so
the approver can correlate.”
cli, terraform and console are deliberately NOT kinds. The daemon
authenticates a principal, not a binary. shc install against a remote
daemon, the terraform provider and a console click all arrive as the same
bearer token from the same realm user; the only thing that could tell them
apart is a self-declared string in the request, and a field a caller fills in
about itself is not evidence.
local: exists so that NULL keeps meaning one thing. A caller on the
daemon’s unix socket is root on a node of this cluster with no realm identity
to resolve. That is recorded explicitly rather than left NULL; an
unpopulated column is worse than no column, because it looks like an answer.
Nothing backfills it, and the third bullet above is why. audit.actor is
“a place to put the answer, not the answer”: deriving installers from a chain
whose actor defaults to the literal "shc" would stamp every pre-existing
deployment as installed by "shc", manufacturing exactly the answer this
column exists to make honest.
Write-once. The column says INSTALLED, not LAST TOUCHED. deployment gets
that from installed_by = COALESCE(deployment.installed_by, excluded.installed_by) in its upsert; several writers reach it with a partial
model (the lifecycle verb recorder, the boot orphan import, recover/clone
replay) and would otherwise blank it, and a converge would rewrite history on
every terraform re-apply. vdeployment gets it from having no second writer:
the install gate stamps the row being BORN and the claim path writes only the
claim. Who converged is audit’s question, on a row per operation.
Derived, not declared. The value is resolved at the one door every install
path funnels through, from the principal the daemon authenticated. A stated
actor is honoured only on the local socket (the portal agent, the one
caller that knows an install came through the portal channel rather than off
somebody’s keyboard), and refused (X400078INSACT) on every other
transport. That is an EVIDENCE boundary, not a privilege one: anything holding
the socket is already root on a node.
9.2 What is still open after ce!114
Section titled “9.2 What is still open after ce!114”The portal ACCOUNT is not on the wire. wire.InstallDispatch is
{app, version, parent_stack, request_id}; it carries no account, so a
portal-dispatched install records the honest bare portal: (“through the
portal, account not on the wire”). Q4’s “installed via portal by <portal account>” is therefore half built: the row can say it, and nothing
tells it who. Closing it needs a field on InstallDispatch and the portal
side filling it in; the cluster half is ready and already refuses that value
from anywhere untrusted.
10. QUESTIONS: three closed, one still open
Section titled “10. QUESTIONS: three closed, one still open”Q4 is for the owner. Nothing above answers it, and no implementer should read a preference into its framing. Q1–Q3 are closed; each keeps its original statement so that the reasoning which closed it is readable against the alternatives it beat.
Q1: Purchasing authority: ✅ CLOSED: request-and-approve
Section titled “Q1: Purchasing authority: ✅ CLOSED: request-and-approve”Closed by 2026-08-16-portal-cluster-identity.md
Ruling 1: candidate (2) below, the request flow.
The owner: “if you try to purchase an app that costs money, it creates a request. It has to be approved. That’s probably my preferred one.”
Pre-approval is not the losing alternative; it is a layer on top. A
spending limit or an allowlist of pre-approved apps is an auto-approval
rule evaluated inside the request flow, not a second path around it.
Every request produces a row whether a human touched it or not, and there is
exactly one grant point. Removing the request path to “just do pre-approval”
would remove the audit record and the escape hatch at once. The mechanics,
recurring-vs-transaction spend, atomicity of check-and-grant, the
portal-side limit, request expiry, are in
2026-08-16-marketplace-entitlement-and-licensing.md
§6.
The original framing, retained:
A tenant manager hits a paid app their cluster is not entitled to. What happens? Three candidate answers:
- Unavailable, with “ask your owner”, simplest, zero new machinery.
- A request flow that notifies the registering account. (Note: this needs the portal to know the cluster owner, which registration already binds, so the prerequisite exists.)
- They buy it personally and claim it onto the cluster.
Precedent is split: ABM separates purchasing from deployment entirely, which argues for (1) or (2); the request flow (2) matches the shape of the rest of this document most closely.
Q2: Do FREE installs require a portal account? ✅ RULED: YES (owner, 2026-08-16)
Section titled “Q2: Do FREE installs require a portal account? ✅ RULED: YES (owner, 2026-08-16)”“Free installs still need a portal account because we need to know where to install it. At least if it’s through the marketplace.”
RULED: YES. The store is one central store, and every install that goes through the marketplace runs through the §5 handoff shape. The column labelled YES in the table below is the ruling.
The reasoning matters more than the ruling, because the obvious objection has an answer. The objection is: §5 already solves “which cluster”; the assertion is minted by the target cluster and bound to its id, so the store learns the destination without anybody logging in. That is true, and it covers only the launcher-initiated path.
A visitor who arrives directly from search carries no assertion. They did not come from a console; there is nothing to have minted one. The store genuinely cannot know which cluster to install onto, not “can guess badly”, cannot know. An account with linked clusters is how it knows.
And direct arrival is not the edge case; it is the point of the SEO work. §1 already rules that the storefront must serve unauthenticated browsers because a crawler has no account; the per-app landing pages exist to make search the front door. Once search works, direct arrivals become the dominant path, and a design that only knows the destination when the user came from a console is a design that knows the destination in the shrinking minority of cases.
★ The consequence for §5, stated plainly so §5 is not misread: the cluster-minted assertion is demoted to a CONVENIENCE, not the identity mechanism. What it buys is that it skips the cluster picker; the user who arrived from a console does not choose from a dropdown, because the assertion already said which cluster. What it is not is the way the store learns who you are or what you own; that is the account, always. §5’s security properties (§6, anti-replay) are unaffected; they were always about which cluster may be targeted, never about who the user is.
The trade this accepts, named rather than glossed: two logins for everyone, including free users. That is the cost column of YES, and it was paid knowingly. What it buys is in the last row.
| YES: free installs need a portal account ← RULED | NO: free installs need no portal account | |
|---|---|---|
| store topology | one central store, full stop | central store plus a per-cluster catalogue surface |
| install path | new-tab signed handoff (§5) for everything | local surface for free; handoff only for paid |
| control | maximum: every install is observed centrally | partial: free installs never touch us |
| cost to the user | two logins for everyone, including free users | one login for the common case |
| cost to us | none beyond §5 | we ship storefront code to estates, a second frontend, versioned, updated and supported across every customer estate |
| direct-from-search arrival | works: the account names the cluster | has no destination at all |
The asymmetry originally named, YES is cheap for us and taxes the user; NO is kind to the user and hands us a shipped-to-customer frontend to maintain forever, survives, and the search row is what settles it: NO is not merely expensive, it has no answer for the arrival path we are building toward.
What this does NOT change: two things, and both are in the owner’s own qualifier “at least if it’s through the marketplace”:
- §1(a). Anonymous visitors still browse the whole catalogue with no account, because a crawler has no account and the storefront must stay indexable. The account is required to install, not to look.
- The cluster’s own install surfaces. The ruling is scoped to installs
initiated at the marketplace.
shc installon the customer’s own cluster, and a console-initiated install that never leaves the estate, are untouched; they already know which cluster they are on, so the question the account answers does not arise. That is the same boundary §7 draws for repos: the CLI is the customer’s own surface, invoked by the customer. §1(c) and §2 therefore stand unchanged; a cluster tenant user still installs on their own realm credentials, and entitlement still rides the cluster.
Q3: If a per-cluster storefront surface exists, what is it? ✅ CLOSED: it does not exist
Section titled “Q3: If a per-cluster storefront surface exists, what is it? ✅ CLOSED: it does not exist”Closed by Q2. The per-cluster storefront was only ever live if Q2 resolved NO. It resolved YES, so there is no per-cluster storefront surface, and neither candidate shape below gets built:
A catalogue app an owner installs, opt-in, versioned like any app.A daemon-served builtin, always present, no install step, always current, unconditionally shipped to every estate.
This is the largest thing the Q2 ruling buys: we do not ship storefront code
to customer estates. No second frontend, no per-estate version skew, no
support obligation for a UI running on hardware we do not operate. It also
keeps §11 true without qualification; the marketplace stack on bitspur is
the public storefront, and there is no such thing as a per-tenant
marketplace.
Q4: When the PORTAL dispatches an install, whose authority does the daemon act under? (still open)
Section titled “Q4: When the PORTAL dispatches an install, whose authority does the daemon act under? (still open)”The problem is real: the portal user is not a cluster identity. There is no realm account to run as.
RECOMMENDATION, explicitly NOT a ruling: execute as the cluster
REGISTRATION principal, and record the row as “installed via portal by
<portal account>”. Authority is the machine’s; the audit trail names a
human. This is precisely what GitHub does (the installation access token
carries the authority, the installation record names the user who clicked
(§8)), and it is the natural consumer of the §9 fix.
UPDATE 2026-08-18: the RECORD half of that recommendation now exists;
the AUTHORITY half is still unruled. ce!114 gives the deployment row a
portal:[<account>] actor, so “installed via portal by …” is now sayable.
Two things it does not settle, and neither should be read into it: whose
authority the daemon acts under is still the open question this Q4 asks,
untouched; and the <account> half is not populated, because the dispatch
wire carries no account (§9.2). A portal install today records portal:,
the channel, honestly, without the human. Landing a column is not answering a
question about authority, and this section stays OPEN.
The owner has not ruled on this. It is written down as a recommendation so that the alternative, inventing a shadow cluster identity per portal user, is a decision someone has to make on purpose rather than by drift.
11. Clearing up a real confusion: the marketplace stack on bitspur
Section titled “11. Clearing up a real confusion: the marketplace stack on bitspur”This caused genuine confusion and is worth stating flatly.
The marketplace stack deployed on the bitspur estate IS the PUBLIC
STOREFRONT. It is not a per-tenant marketplace, and there is no such thing
as a per-tenant marketplace.
Verified 2026-08-16: marketplace.selfhostedcloud.org resolves to
37.27.215.210, which is the bitspur estate leader
(compose01.hel1.hetzner.bitspur.com), the same address named throughout
docs/reference/quota-model-state.md, docs/guide/operations/, and the GRC
evidence bundle.
It is the central store that happens to run on our own estate. We are our
own first customer; the storefront is deployed the way every other SHC app is
deployed. Seeing a marketplace stack in a shc ls on bitspur means the
public store is running here, not this tenant has a store.
Bindings honoured
Section titled “Bindings honoured”The no-iframe ruling (marketplace §1, portal §4), reaffirmed with a second, independent reason. The federation carve-out (portal §2), unchanged, and its one-way property is now written down as a trust boundary. “Accounts own purchases; the portal claims them onto registered clusters” (marketplace §2), extended, not replaced. The registration gate (portal §3), unchanged; the assertion in §5 is signed with the credential registration issues. ce carries none of this: the registration credential, the assertion mint and the portal channel are shc-proprietary (portal §2, Placement).