Flow: the launcher
Layer 10. Edge. Edge
The apps menu injected into pages across the estate: how it establishes identity on a host that has no SHC session, why it is built the way it is, and what it cannot do.
Source of truth:
traefik/plugin/launcher.go: the three endpoints, the silent OIDC check, the handle store.traefik/plugin/menu.go: the injected payload, the credential reader, the rendered menu.ce/modules/auth/launcher.go: the mode axis, the middleware config, the injected<script>.ce/modules/app/inject_traefik.go: which routers the middleware is chained onto.
Related: authentication is the estate-wide picture: every way identity is established and what is armed. This page is one subsystem in depth.
§1-§11 describe what ships. §12 is the design record for the inventory redesign (one entry per app rather than per host, an environment filter, icons on the tiles) and everything in it is either a measurement or marked PROPOSED. §13 lists what the owner still has to rule on. §14 describes the trigger’s position, which ships.
Section numbers are an interface. ce cites this document by number
(launcher.md §8, three call sites in modules/auth/ and
modules/app/), so sections are APPENDED and never renumbered. That is
why the trigger’s position is §14 rather than the §12 its own lane wrote
it as: §12 and §13 were already claimed by the inventory record, whose
fifteen internal §12.x back-references would otherwise all have had to
move. The lane’s code comments were updated to match, not the other way
round.
1. The problem
Section titled “1. The problem”The menu was unreachable on exactly the apps it was wanted on.
Its original identity check proved callers from shc_access_token,
which the forward-auth gate mints, and only on the gated leg. Every app
carrying its own native SSO (GitLab, Nextcloud, AFFiNE, Huly, Frappe) is
deliberately ungated, because gating an app that runs its own OIDC
puts the app’s callback behind the gate and breaks its login. So on
precisely the apps a user spends their day in, that cookie never existed.
Measured on bitspur 2026-08-09: data-shc-launcher present and
shc-apps-menu absent on every ungated app on the estate.
The ruling that followed: the launcher must authenticate the user itself, against the estate’s Keycloak, independently of the route gate.
2. The central decision: same origin, everywhere
Section titled “2. The central decision: same origin, everywhere”/.shc/launcher/ is a reserved namespace on every hostname the proxy
serves. The Traefik plugin intercepts that prefix before the request
reaches the backend; nothing under it is ever proxied to the app. /.shc/
is not a path any application ships, so no app route can be shadowed by
accident (launcher.go:120-125).
The callback URL is built from the current request host:
func (i *menuInjector) launcherCallbackURL(r *http.Request) string { return gateRequestProto(r) + "://" + gateRequestHost(r) + launcherCallbackPath}Everything therefore stays same-origin with the page: the inventory XHR,
the cookies, the postMessage target. That single choice buys four
security properties for free, each of which would otherwise be a
configuration to build and get right:
| Property | How it comes free |
|---|---|
| No CORS surface | The inventory XHR is same-origin, so the endpoint refuses cross-origin reads outright: no allow-list to maintain. serveLauncherApps sets no Access-Control-Allow-Origin, ever. |
| Tenant binding | The tenant is derived from the request host, because the endpoint is on that host. No untrusted caller-supplied origin to validate. |
| State binding | The signed state names the callback URL it was minted for, so a state minted on one host of the estate cannot complete on another (launcher.go:543-548, re-checked at the callback). |
| Host-only cookies | No Domain attribute anywhere. Nothing becomes ambient across the estate. |
The price is that the callback URI is now per-host and cannot be
enumerated in advance, which is the origin of redirectUris: ["*"] on
the shc-forward-auth client. See §9.
3. The reserved endpoints
Section titled “3. The reserved endpoints”All under /.shc/launcher/, all served by the plugin, all 404 for any
other path in the namespace and 405 for anything but GET/HEAD.
| Path | Role |
|---|---|
/apps | The inventory. The only place an app list ever leaves the proxy. |
/start | Begins the silent check. Loaded in a hidden frame; answers a 302 to Keycloak. |
/callback | The silent check’s return. Redeems the code server-side and mints the handle. |
/shell/<hash>.(js|css) | The launcher-shell bundle. Static, content-addressed, no identity required; the names ride only the authenticated /apps response. |
/icon/<sha256>.(svg|png)?k=<key> | A tile’s picture. Content-addressed, cached public, max-age=31536000, immutable with the hash as ETag; answers only with the key /apps hands out. §12.8.1. |
/layout | Retired (FZ-8531). GET/HEAD answer 404; all other methods answer 405. Stored arrangements remain readable through /apps. §25. |
Since 2026-08-13 the owner has approved THREE widenings of this set:
- the static prefix
/.shc/launcher/shell/*(2026-08-13), which serves the daemon-materialised launcher-shell bundle. §18 carries the ruling and the file contract, §19 the plugin’s serving and loader half. /.shc/launcher/layout(2026-08-16), the cross-origin launcher layout, and the FIRST endpoint in this namespace that changes anything. §25 carries the ruling, the CSRF ladder that answers the objection the old design was refused on, and the merge rule.- the static prefix
/.shc/launcher/icon/*(2026-10-18, SHC-3519), which serves the tiles’ pictures so/appscarries names instead of data: URIs. §12.8.1 carries the contract.
The layout widening is retired. Every path in the namespace answers
405 to anything but GET/HEAD, including /layout. Widening the set
again remains an owner decision.
4. Session and cookie inventory
Section titled “4. Session and cookie inventory”Four independent sessions are in play, and confusing them is the usual source of error. Only two of the four belong to SHC.
| Session | Owner | Host | Meaning |
|---|---|---|---|
| Keycloak SSO | Keycloak | auth.corp.<estate> | The only one that means “who you are”. |
| App session | the app | the app’s host | Opaque to everyone but the app. |
shc_access_token | forward-auth gate | the app’s host, Path=/, Lax | Gated routes only. |
shc_launcher | the launcher | the app’s host, Path=/.shc/launcher/, None, 30 min | An opaque handle, not a token. |
Plus two short-lived CSRF cookies (shc_oidc_state (gate) and
shc_launcher_state (launcher, Path=/.shc/launcher/, 5 min)) and
shc_id_token on the gate’s logout path.
One more, and it is the only cookie here a script is meant to read:
shc_launcher_open (Path=/, Lax, Secure, not HttpOnly, 60 s). The
callback sets it when the signed state says a press began the round
trip, and the payload reads it and deletes it in the same breath. It
carries no identity and authorises nothing; its whole content is 1, and
its whole job is “open the menu once, for the press that asked”. See §24.
SameSite=None on the launcher’s cookies is required, not a
weakening: the callback can be reached by a cross-site redirect landing
inside a frame, which is always the case when the app host and the auth
host sit on different registrable domains (§8). The cookies are HttpOnly,
Secure, path-scoped to the plugin’s own prefix, and the state cookie’s
entire authority is “a callback may complete”.
shc_launcher is a handle, not a credential. The access token is
held in memory inside the middleware, keyed by a random handle; the
browser only ever receives the handle, HttpOnly. It buys one endpoint
and nothing else, and no script can read it.
5. The framing that makes it legible
Section titled “5. The framing that makes it legible”On an ungated app the inventory XHR returns 401, and the reason people get stuck here is that “not authenticated” is true in one sense and false in the other:
- Not authenticated to SHC. No
Authorization, noshc_access_token(never minted; the route is ungated), noshc_launcheryet. That is what the 401 reports, and it is correct. - Authenticated to Keycloak. The user logged in at
auth.corp.<estate>moments ago to get into the app. That cookie exists. SHC simply cannot see it, because it is on another host.
The 401 is therefore not a dead end. It is the trigger for converting the second fact into the first.
The app’s own cookie is no help, and the reason is worth stating
precisely: it is delivered to /.shc/launcher/apps (same host,
Path=/) and the plugin can read the bytes. It is an opaque identifier
that only resolves inside the app’s own session store. Not signed, no
claims, unverifiable by anyone else. So the plugin does not even look at
it: menuCredentialOf reads exactly the Authorization header and the
shc_access_token cookie (menu.go:485-495). Everything else on the
request is ignored, not rejected.
This is not an SHC limitation. It is how OIDC works. Apps never share sessions; each independently obtains its own proof from the IdP. The launcher is one more party doing exactly that.
6. The full trace
Section titled “6. The full trace”Fresh browser, ungated app with native SSO (GitLab on bitspur), launcher
mode auto.
Phase 1: the app logs you in. SHC is not involved.
GET git.corp.bitspur.com/. Traefik proxies; there is no gate. GitLab serves its login page. The plugin injects its script into that HTML; the visitor is anonymous, so what the script renders is the sign-in offer, a trigger, never a menu (§6,prompt=none).- GitLab’s own auto-redirect fires and sends the browser to Keycloak
with GitLab’s
client_id. - The user authenticates at
auth.corp.bitspur.com. Keycloak sets its own session cookie on its own host. This is the cookie everything downstream depends on. - Keycloak returns a code to GitLab’s callback. GitLab redeems it with its own secret and sets its own session cookie.
- The dashboard renders; the plugin injects the launcher script into it.
Two cookies now exist on two hosts. Neither belongs to SHC.
Phase 2: the launcher obtains its own identity.
- The script XHRs
/.shc/launcher/apps. No credential the plugin can read → 401, empty body. - That 401 triggers
probe(), which creates a 1×1 hidden iframe parked atleft:-10000px, pointed at/.shc/launcher/start. /startasks the daemon for this host’s realm and client, mints a signed state bound to this host’s callback, setsshc_launcher_state, and 302s the frame to Keycloak withclient_id=shc-forward-auth,scope=openid, andprompt=none.- The frame navigates to
auth.corp.bitspur.com, so the browser attaches the cookie from step 3. Keycloak recognises the session and, forbidden from rendering UI, answers 302 with a code. - The frame lands on
/.shc/launcher/callback. The plugin checks the state cookie against the state parameter, verifies its HMAC, and confirms the state was minted for this host. It then POSTs the code plus the confidential client secret to Keycloak’s token endpoint, server to server. - Keycloak returns an access token over that back channel. The plugin
stores it in memory under a random handle and sets
shc_launcher=<handle>. The callback pagepostMessagesokto the parent; the parent verifies bothe.originande.sourceand drops the frame.
Phase 3: the inventory.
- The script re-runs the same XHR. It now carries
shc_launcher, which the plugin resolves back to the token. - The plugin proves the identity with the daemon (§7), intersects the
verdict with this tenant’s routed hosts, and answers with
Cache-Control: private, no-storeandVary: Cookie, Authorization. - The script builds the menu into a shadow DOM inside a fixed div
pinned to all four viewport edges with
pointer-events: none.
What a tile is: an icon, not a name
Section titled “What a tile is: an icon, not a name”A tile is a square carrying one picture and no visible text. Its
accessible name is not visible text either way: aria-label and title
on the anchor both carry <app>: <verb>, and the <svg> is
aria-hidden="true" focusable="false", so exactly one name is announced
per tile whether or not any art resolved.
The art is an inline SVG built with createElementNS, and that is
the whole reason it is free. An <img>, a background-image or a CSS
mask are all fetches, which img-src governs; cooperating with
img-src would mean a third editor in csp.go and a new claim on
somebody else’s policy. Elements are markup, not fetches, so no CSP
directive applies to them at all, exactly as the SHC mark is three
positioned spans rather than a data: URI. Measured against SonarQube’s
real policy and against a deliberately image-hostile one
(img-src 'none'): the launcher renders and img-src, style-src,
font-src and media-src come out byte-identical.
The geometry rides the /apps response, in a glyphs map deduplicated
to one path per distinct category present, with a short i key per
tile. It does not get a fourth endpoint: the three endpoints in §3
are a security-relevant constant, and 1,929 bytes of sheet on a 3,151-byte
response (measured: 16 tiles spanning 14 categories) is cheaper than a new
path in the reserved namespace plus a second round trip and its failure
mode. It
costs the injected payload (the byte-ceilinged artifact that lands on
other people’s pages) 284 bytes, because the name and hostname lines it
replaces were larger than the renderer that replaced them.
The glyphs are keyed by the catalogue’s own category:, through an
app-name table in traefik/plugin/icons.go that mirrors every packaged
app. 81 of the 91 packaged apps (89.0%) resolve to art; the rest, and
every deployment installed after the image was built, render a
monogram: two characters of the label in a hue derived from it. That
is the common path, not an error path: the table is baked into an image
and the catalogue grows on its own clock.
The catalogue’s own icon: field is deliberately unused. 76 of 91
apps carry one, and every value is an absolute third-party HTTPS URL
across 57 distinct origins. Rendering them would owe an img-src
concession naming 57 foreign hosts on every app the launcher rides on,
and would beacon every user’s browser to 57 vendor CDNs from a page
belonging to somebody else’s organisation. Vendor logos are a separate
question (a trademark one), and the table is app-name keyed so that
ruling lands as data, not code.
The one-line version: the app’s login and the launcher’s login are two independent OIDC flows against the same Keycloak, using different clients and different redirect URIs, run minutes apart. The only thing they share is the Keycloak session cookie from step 3, and the second is silent purely because the first already created it.
Why a frame and not a fetch
Section titled “Why a frame and not a fetch”A fetch() to Keycloak’s authorize endpoint cannot do this. It is
cross-origin: CORS blocks reading the response, Keycloak sends no
Access-Control-Allow-Origin, and a fetch cannot usefully complete a
redirect chain that lands back on the original origin and sets a cookie
there.
An iframe navigates like a tab. It follows 302s across origins, the
browser attaches each host’s cookies as it goes, and it ends up back on
the parent’s own origin, where it is finally same-origin and can
postMessage. It is the only browser primitive that makes that round
trip invisibly.
What prompt=none guarantees
Section titled “What prompt=none guarantees”Two things, and both are load-bearing.
It can never log anyone in. Keycloak answers from the existing
session or returns login_required. Nothing is signed in silently, no
login form is ever rendered, and no prompt interrupts anybody, which is
what makes this safe to run on a page belonging to someone else.
login_required is not a dead end, and since 2026-08-11 it is not a
silence either. On that answer the payload renders its sign-in offer:
one floating 52px trigger, no dialog, no inventory, no navigation until it
is pressed. That is also what a local app password login now
produces. It creates the app’s session without ever creating Keycloak’s,
so the probe answers login_required and the user is offered the SSO
login the menu actually needs, where before they got no menu and no
explanation.
Expired and anonymous are the same answer, deliberately. Nothing the
browser can see distinguishes “the SSO session died under me” from “I have
never signed in here”: /apps and /start refuse identically in every
failure case on purpose (§7), and a payload that could tell the two
apart would be a disclosure channel rather than a feature. So the offer
renders for both, and a genuinely anonymous visitor to a launcher-enabled
page sees the trigger too. Two things bound that cost:
- the trigger does nothing until pressed. No dialog is thrown at a
stranger, no app is named, and the one
location.assignin the payload is reachable from the press handler alone. - the page had to opt in.
Inject()refuses any body that does not already carrydata-shc-launcher, and under the shipped default (launcher: button, §8) an ungated app gets no injected script at all. A public marketing page only reaches this at all on an estate whose operator setlauncher: auto.
The alternative was the defect this replaced: the SSO session dies while an app’s own session lives on, so the app keeps serving a signed-in page and the launcher vanishes off it. Same silence, no way for the user to act on it.
The two edges that are not verdicts
Section titled “The two edges that are not verdicts”Ungating the offer on “not-ok” widened it past the three answers Keycloak
can give onto two states that are not answers at all. They go in opposite
directions, both deliberately, and both are pinned by name in
tests/unit/traefik/crosssite_test.go.
No verdict at all renders the offer. The frame is blocked by a privacy
mode or an extension, Keycloak is slow, the network is gone: the probe’s
timeout, f.onerror or its addEventListener catch fires and the payload
learns nothing. It offers anyway, because every leg the button drives
survives a dead frame; the click-through is a top-level navigation that
needs no frame, and the forced-silent retry that precedes it rescues the
merely-slow case with no navigation at all. Treating silence as failure
would hide the launcher from precisely the browsers whose only working
path is the button.
An unavailable verdict renders nothing. launcherFailed answers an
ok=0 page too (for an unconfigured OIDC block on the router, an
unreachable daemon, a state it could not sign) and its bytes are
identical to login_required’s by design, because one shape per outcome
is what keeps the callback page’s CSP hash constant. In those states the
offer would be a dead button: pressing it runs /start?silent=1 (503,
ok=0), then the top-level /start?return=<path>, which the same broken
handler answers with a redirect straight back to the page the press came
from. A full reload that lands where it started, with the button still
there, grown on every launcher-carrying page in the estate at once during
a daemon outage.
So the verdict page carries a third flag, data-shc-un, and the payload
suppresses the offer on it. It is derived from the HTTP status in
launcherAnswer: every 200 is an answer about the caller (proven,
login_required, cross-site) and every non-200 is this proxy saying it
could not begin a sign-in at all. That is not a hole in §7’s
refuse-identically rule and not a disclosure channel; un reports the
proxy’s own health, which the status line already states in the clear, and
every verdict about a caller is still a 200 that the payload cannot tell
apart from any other.
No Keycloak document is ever rendered in the frame. The authorize
endpoint answers with a 302, not a page. X-Frame-Options governs
documents rendered in frames, so it never applies. Any design that
renders a Keycloak page in a frame would have to relax
frame-ancestors on the origin that serves the login form.
7. The credential ladder
Section titled “7. The credential ladder”serveLauncherApps refuses identically in every failure case: 401, no
body, no hostname, no hint of which rung failed. A caller learning “you
are cross-tenant” rather than “you are nobody” would itself be a
disclosure.
- Resolve the tenant from the request host. Unrouted host → 401 before any daemon call.
- Read the credential:
Authorization, thenshc_access_token. If both are absent, resolveshc_launcherto its stored token. - Prove the identity with the daemon. A proven identity whose tenant differs from the host’s tenant → 401.
- The entitled-elsewhere rung. If direct proof misses, fall through
to
/api/user/effective-apps.
Rung 4 exists because of a measured defect worth recording.
/api/auth/forward-auth is the gate’s per-deployment authorization
endpoint; it ends in 403 missing_role for any caller lacking
stack:<this host's app>:use. Using it as the launcher’s proof asked
“may you open the app you are already looking at?” rather than “who are
you?”, and rendered nothing on a 403.
Measured on both estates 2026-08-09: 43 users in bitspur’s corp realm, of whom exactly one held any stack role at all, and that role was on the one app that was down. The launcher was invisible to 43 of 43 real users on every host, while the payload, the silent check, the handle mint and the CSP hash were all provably correct. Five rounds of marker-counting passed against a feature nobody could see.
/api/user/effective-apps never 403s. It is self-scoping, and a caller
entitled to nothing gets 200 and an empty list. A 200 is therefore proof
of a credential the daemon accepted, which is exactly what an app
switcher needs. Nothing is widened: the rendered list is still the
verdict intersected with this tenant’s routed hosts. What changed is the
host a caller may see their list from.
7.1 There is exactly one rung that answers a list, and it is the filtered one
Section titled “7.1 There is exactly one rung that answers a list, and it is the filtered one”Owner’s ruling, 2026-08-16: the degraded rung is deleted.
resolve used to have two rungs: the permission-filtered list, and, for
a proven caller whose verdict the daemon could not supply, the whole
tenant’s routed apps. The fallback was wider than the rung it backed,
which is a fallback that falls open.
Measured on bitspur’s own apps.json, replayed through the real endpoint
(traefik/plugin/testdata/estate_bitspur_apps.json, and
launcher_disclosure_test.go re-derives both numbers on every run):
31 stacks in apps.json (39 routed-host rows, one tenant)-2 placed:false gitlab-huly, license-broker-1 nextcloud-picker folds into nc=28 the tenant's routed set-4 ivatar, netbird, paperless, uptime: no grant held=24 what the filtered rung USED to answer★ SUPERSEDED IN PART BY THE RULING OF 2026-08-16: see §7.1.1. The arithmetic above is still exactly how the two numbers arose, and it is still why the old fallback was a disclosure. What changed is the answer: the authoritative rung now answers 28, because the owner ruled that every app the tenant runs is displayed by default and the four ungranted ones are marked, not withheld. The last line is therefore history, not behaviour. Crucially the fallback is not what widened; the top of the ladder came down to meet it, so no rung discloses more than the rung above it and the guard passes without its expectation being edited.
Which of the two a member saw was decided by daemon health at that
instant, and the two hosts the owner compared were not really two
hosts; they were the two rungs, selected by each host’s access:
| host | access | rung reached | tiles |
|---|---|---|---|
mail.corp | open | no gate → forward-auth 403 → the entitled-elsewhere rung, which requires a verdict | 24 |
agents.corp | gated | the gate proved the caller → resolve → cold verdict → the tenant-wide fallback | 28 |
So mail was correct at the time and agents was
over-disclosing at the time, and under §7.1.1 both hosts now answer
28, identically, which is the property the owner actually asked for
(“the same tile count everywhere for the same identity”). The
trigger is not theoretical: the daemon answered 429 on the 2nd of 6
rapid probes on this estate, and every cold cache key was another
chance to land on it.
What replaces the fallback:
- Serve the last-good verdict when one exists, past its TTL. This is
what
menuClient.Verdictalready did one layer down, and it is now the whole of the degradation story. - When no verdict has ever been obtained for that caller, render no launcher. Not a wide one.
- A decided 401 ends last-good. A daemon answering “this credential is
not one” is not a health failure, and a revoked token must stop being
answered from cache. Everything else (transport, timeout, 5xx, 429)
is undecided and keeps it. That is
refusal.go’s DECIDED/UNDECIDABLE split applied to the cache.
This does not conflict with “tiles never hide” (§12.5). That ruling is about entitlement: an app you hold no role for still gets a tile, and tapping it routes somewhere useful. It is a decision made from a verdict. This is about daemon health (no verdict at all) and showing apps because we could not find out what you may open is not discoverability, it is a disclosure of what exists in the tenant.
The cost is bounded and worth naming: last-good covers every caller who
has opened the launcher once since the process started, so “no list” is
confined to a genuinely cold caller during a genuine outage, and, on an
estate whose daemon has no /api/user/effective-apps at all, to every
caller. An un-rolled daemon now shows no launcher where it used to show
the whole tenant.
7.1.1 Everything shows: the verdict supplies the VERB, the file supplies MEMBERSHIP
Section titled “7.1.1 Everything shows: the verdict supplies the VERB, the file supplies MEMBERSHIP”Owner’s ruling, 2026-08-16, in three parts. The third is the mechanism and all three have to hold together:
- “every app in the tenant by default would be displayed, unless you explicitly turn it off.”
- “Take that back. No. My default, just everything. Like, actually, everything, everything. That’s the default, and that’s what I want.” (Retracting his own environment scoping.)
- “we have a precedence order for which environment it goes to when you click on it. Right? and all the other environments. It’s one icon per stack. But all the deployments and environments will show up in the menu when you right click or long press.”
Stated as a model:
ONE TILE PER STACK not one per deployment, not one per environmentTAP / CLICK -> opens that stack in the PRECEDENCE-ORDERED environmentLONG-PRESS / -> a menu of that stack's control surfaces (Open, its vapps,RIGHT-CLICK and one row per Management tab)DEFAULT -> everything shows: no grant filtering, no environment filtering. Only an explicit per-app opt-out removes a tile.★ AMENDED 2026-08-17: CLAUSE 3 ABOVE IS SUPERSEDED IN ITS MENU HALF.
The ruling transcribed above ends “But all the deployments and environments will show up in the menu when you right click or long press”, and this document went on presenting that as law after the owner withdrew it the following day:
“in the menu with the apps or whatever we shouldn’t support listing environments in the right click. instead you should be able to switch the console to another environment. (for floating menu you don’t change and can’t change the environment as it’s already known).”
What still holds: one tile per stack, tap opens the precedence-ordered environment, everything shows by default, and the per-app opt-out. Those are untouched.
What does not: the menu does NOT list a stack’s other deployments or environments. A launcher tile is single-environment: which deployment it opens is resolved by
launcher.environment_precedenceand is not a per-tile choice. Crossing that axis is the CONSOLE’s business, via the environment scope in its account menu (features/console/src/springboard/AccountButton.tsx).Enforced in all three surfaces: the plugin’s
ekids went fromtraefik/plugin/menu_stack.go,packages/springboard-ui/src/StackMenu.tsxcarries the ruling in its header and has no environments section, anddedupeMenuEnvironmentsdrops the losing deployment outright (TestDedupeMenuEnvironmentsDropsTheLoserEntirely).This note exists because the superseded sentence sat here as law for a day and a half while lanes read this file to build from.
Two filters were removed and one was not.
| filter | before | after |
|---|---|---|
grant (resolve) | entries the verdict did not name were dropped | entries the verdict does not name are kept and marked u |
environment (menuEnvPolicyAdmits) | auto (the shipped default) listed only the request host’s environment | auto is an alias for all; only an explicitly named environment still filters |
| tenant | e.Tenant != tenant | unchanged; this is the boundary the ruling did not move |
Measured on bitspur’s live apps.json (46 corp rows, 2026-08-17): the
answered set goes from 24 tiles to 33, the nine additions being
immich, ivatar, netbird, paperless, peertube, postiz, supabase, superset, uptime, every one of them routed for the tenant and
previously invisible to its own operator. On the frozen 39-row test
fixture the same change reads 24 → 28.
Why a flag and not a drop. ce’s effective-apps API omits an app the
caller holds no verb on (modules/user/types.go: “a VerbNone app is
ABSENT from it (R-e), not listed with verb:none”), so absence is the
only signal available. resolve now reads that absence as a fact about
the tile: menuTile.unentitled → payload u → the grid paints the tile
at 50% opacity. The tap still navigates, forward-auth still refuses, and
the refusal is what routes the caller somewhere useful.
The precedence order was not invented for this; it already existed.
menuEnvPrecedenceDefault in traefik/plugin/menu.go:
var menuEnvPrecedenceDefault = []string{ "prod", "live", "staging", "stage", "default", "test", "qa", "dev", "development",}An estate overrides it with the environmentPrecedence config key at
tenant or global scope, which ce resolves per tenant and stamps as
envprecedence on every row of that tenant; the plugin reads it off the
request host’s entry (menuEnvPrecedenceFor). Unlisted names sort
after every listed one, alphabetically. It is shared verbatim with the
console’s DEFAULT_ENVIRONMENT_PRECEDENCE. On bitspur today no row is
stamped at either scope, so the built-in order above is what is in
force.
The explicit opt-out is launcher_placed / launcherPlaced, which
already existed and needed no new knob. An app declares
launcher_placed: false in its app.yaml (today: gitlab-huly, a
webhook with no page); an operator overrides that in both directions
through the ordinary scope cascade, e.g.
shc config set launcherPlaced false --scope deployment -t corp -s superset -e prodIt is auditable like any other config key (shc config get), and it
resolves per deployment, which answers the “whole tile or one menu
entry?” question correctly and without a second mechanism: unplace the
only deployment of a stack and the tile goes; unplace one environment of
a three-environment stack and just that long-press entry goes, because
the tile is drawn from whichever deployments remain. A stack-level
switch would be unable to express the second case at all.
What “everything” does NOT mean: tenancy still bounds it. A corp
identity must never see an shc, desibox or master app. The launcher
resolves the tenant from the request host (menuTenantOf) and
separately refuses any identity whose own tenant differs, so the boundary
holds on every rung. Two named guards hold it:
TestTenantIsStillTheBoundaryUnderEverythingShows and
TestNoRungDisclosesBeyondTheCallersTenant; the latter asks every rung
over a file that really does route a second tenant, including a rung
whose daemon actively grants that foreign tenant, and names the leaked
host when it fails.
Cross-tenant browsing for a platform admin is NOT implemented, and is
left for a ruling. platform:manage is the only cross-class
implication in the role grammar (daemon/wiring/user_role_gate.go), but
the launcher never consults roles when scoping: it filters on the request
host’s tenant and refuses a mismatched identity outright. So a platform
admin standing on a corp host sees corp, and standing on a master host
sees master only if their identity is master. The two options, with their
costs:
- Leave it (current behaviour). The launcher stays a per-tenant surface with one rule; cross-tenant browsing stays the console’s job. Cost: an operator of the whole estate cannot reach another tenant’s app from the switcher.
- Let
platform:managespan tenants. Cost: the tenant filter stops being a constant and becomes role-dependent, so every disclosure guard in the ladder needs a per-caller expectation rather than a fixed one, which is the shape of guard that has already failed this feature twice.
7.2 The verdict cache is keyed by (credential, tenant)
Section titled “7.2 The verdict cache is keyed by (credential, tenant)”ListEffectiveApps reads ?host= for exactly one job: resolve which
tenant owns that routed host, then answer that tenant’s deployments.
Two routed hosts of one tenant therefore produce byte-identical answers,
so the old per-host key cached the same bytes under K names: 39 rows
over 31 stacks here, 4 hosts on matrix alone.
That cost twice: request rate (a caller roaming K hosts paid K
identical daemon calls per TTL; 39 worst case, now 31) and
divergence (each cold key was another chance to fall to the rung
above). The tenant is never taken from the caller. serveLauncherApps
derives it from apps.json via menuTenantOf before any daemon call.
The cache is process-wide. ce generates one
shc-launcher-<project> middleware per deployment (31 on bitspur),
and each calls New() and built its own client, so tenant keying alone
would still have left 31 independent caches over one file and one daemon.
The store is a package-level verdictStore guarded by its own lock;
Traefik builds one Yaegi interpreter per plugin and calls the resolved
New for each middleware definition, so package vars are per-process.
Keys hash the credential and the daemon URL, so two instances collide
only where they are asking the same daemon the same question for the same
caller.
7.3 A grant reaches the list on the next open (FZ-8575)
Section titled “7.3 A grant reaches the list on the next open (FZ-8575)”ce derives the list’s verbs from the token’s claims, so the list is only as new as the token behind it. Both credentials renew on the gate’s cadence (near access expiry, or halfway through the refresh window: up to about 15 minutes on Ogden), and the cache above holds an answer 30 s on top. A grant made after sign-in used to take minutes to reach the panel and the floating menu.
/apps and /panel now read the list with a token at most 5 s old:
| Credential | Who renews | What the read skips |
|---|---|---|
launcher handle (shc_launcher, app hosts the gate does not cover) | the plugin, one grant per handle per 5 s, single-flight; a read that finds a grant in flight waits for it | the cached identity and verdict, when its token was renewed during this read |
gate handle (shc_access_token=shcsess.…, gated hosts) | forward-auth, on the /apps or /panel call itself, one grant per session per 5 s, bound to shcd before the plugin reads | any cached identity or verdict older than 5 s |
Neither spends a refresh token that has already expired: a session whose Keycloak idle window has closed keeps its live access token, exactly as an ordinary request would. A refused grant ends the handle or the session, as the regular renewal does. A revoke shows the same way, on the next open after 5 s. Every other caller (the layout store, page injection, a bearer) keeps the 30 s cache and the regular renewal.
The unit of the list is an APP, not a routed host
Section titled “The unit of the list is an APP, not a routed host”apps.json is one entry per (deployment, routed host); it has to
be, because it is also the authority menuTenantOf reads to answer
“which tenant owns this hostname”. A deployment answering on three
hostnames is three entries, and until this rule the switcher drew three
tiles for one app.
dedupeMenuTiles collapses them after resolve and before the
maxMenuEntries cap, so the verdict filter still sees the full host set
and the cap counts apps rather than hostnames. (It used to have a second
reason (the degraded rung read a per-host verb off the proof call), and
that rung is gone as of §7.1.)
The key is the deployment ((tenant, environment, stack), the same
key the verdict is keyed on), never the stack name. Two environments of
one app are two separately reachable, separately entitled things;
folding them on the stack name would silently delete one of a caller’s
apps with no way to reach it. Collapsing the environment axis is the
operator’s decision, below.
Which host the one tile links to, in order:
- A browser-facing host beats an
apione, always. The app.yamlhost_roles:map names the compose services a browser must not be sent to; the daemon joins it to each routed host through the host’s ownservice=selector and publishes the verdict asroleon the file record. This rung is FIRST because everything below it is order, and order is what Terraform destroys; see the box below. The marker is optional and absent means browser-facing, so this rung is a no-op on every deployment that has not declared one, and it can only ever reorder within a deployment: an all-apideployment still gets its tile. - The request’s own host, when this deployment routes it. Below the
role rung deliberately: standing on the API host is exactly when the
tile most needs to point somewhere readable.
currentdoes not become a lie, because it is computed over the WHOLE GROUP before the collapse (menuTile.current) rather than off the surviving host, which also closes the §12.6 case where a caller standing on the non-surviving host lost theiraria-currentaltogether. - The host the daemon marked
primary: the deployment’s first declared--expose, derived fromhost_mappinginsertion order. This is already the host/api/user/effective-appsbuilds itsurlfrom (modules/user/service.goappURL, frozen by RBAC §7.1.2), so the switcher’s link and the API’s link are the same link. - The first entry in file order (alphabetical by host), reached only
against a daemon predating the
primaryfield, a stable link rather than a correct one, so an un-rolled estate degrades to today’s behaviour rather than to no link.
primary has to be a field because BuildAppsMenu sorts the file
alphabetically and destroys declaration order on the way out.
Why
Section titled “Why primary alone is not enough: Terraform has no order”primaryalone is not enough: Terraform has no order
shc_deployment.routesis a map. The provider lowers it throughsortedHostInputs, which sorts the route keys, and-(0x2D) sorts before.(0x2E). So<name>-apisorts before<name>every single time: the apiserver becomes the first--exposeargv,primarylands on it, and the deployment’s one tile opens raw JSON in a new tab.Nothing warns, and the operator did not pick a wrong order. A map has none to pick. The moment an existing two-host app is brought under Terraform its tile flips.
host_roles:is declared in the catalogue rather than by the operator because which of an app’s images answers browsers is a property of the app: identical on every estate, knowable at package time. The hostname is the operator’s; the role is not. Declared today bydependency-track(dtrack-apiserver) andmatrix(synapse), and guarded bytests/unit/catalog/host_roles_test.go, which fails if that corpus ever empties.
Which environment the list shows
Section titled “Which environment the list shows”The scoped config key launcherEnvironment names the one environment
a launcher lists. Same idiom as launcher / launcherGzip /
ssoAutoRedirect: resolved through the five-tier cascade (deployment >
stack > environment > tenant > global), re-resolved every sweep, no
reinstall.
shc config set launcherEnvironment prod # estate-wideshc config set launcherEnvironment staging -t corp # per tenantshc config set launcherEnvironment all -t corp # climb back outUnset is auto: the owner’s ruling of 2026-08-11. auto means the
environment of the host the browser is standing on: a page served from a
prod host lists prod, a page served from a staging host lists staging,
and neither lists the other. It satisfies the requirement with nothing
configured, which is what the ruling turned on.
The rejected default was “unset means show every environment”. It is the safe-looking one, and it is the one that ships the defect: an estate that never sets the key keeps the twelve-tile menu forever and the feature exists only for operators who read the release notes; the same invisible-feature failure this subsystem has already shipped once.
all (and *) is the explicit show-everything: the previous default,
still reachable, and the way a lower tier climbs out from under a global
pin, the cascade having no “unset me” value. default and the empty
environment are the same environment; matching is case-insensitive.
The daemon decides, the proxy evaluates, and auto is why. The
first cut of this feature had the daemon stamp a "hidden": true
boolean on each excluded entry. auto cannot be expressed that way:
whether an entry belongs in the answer depends on who is asking, and
the daemon writes ONE apps.json that every viewer of every host reads.
A per-entry boolean would need a different value per viewer.
So the daemon publishes the policy, not the verdict. BuildAppsMenu
resolves the key once per deployment and writes it verbatim as
"envfilter" on that deployment’s entries; serveLauncherApps reads the
policy off the request host’s own entry and applies it when it builds
visible, server-side, in the inventory, never in the injected
payload, which carries no inventory at all and must not start.
Reading the policy off the request host rather than off the candidate is deliberate: “this launcher shows prod” is a statement about the launcher (the page in front of the operator), so the deployment whose page carries it decides. The other reading would let a staging deployment’s own row admit itself into a prod host’s menu.
An empty envfilter reads as all. That is what every daemon
predating the field writes, so an estate mid-roll never loses tiles: the
plugin and the daemon do not ship in the same artifact and never land at
the same instant.
Nothing is ever dropped from the file. The entry stays authoritative
for menuTenantOf, so a host filtered out of one launcher’s list keeps
its tenant, keeps its injected launcher, and is shown the listed
environment’s apps. Dropping the entry instead would answer that host a
bare 401 and take the switcher off it entirely, an outage wearing a
preference’s clothes.
An estate that filters everything out for a tenant refuses with the same bare 401 as every other rung: an empty launcher is worse than no launcher.
The environment suffix follows from this. renderMenuApps appends
(<environment>) to a label only when the answered list actually spans
more than one environment. Under auto (and under any named
environment) it never does, so no tile carries an environment, which is the requirement
(“not even environments listed”). On a mixed list the suffix is the only
thing distinguishing two tiles of the same app, so it is kept.
Latency is two intervals, not one: the clusterfs licence section
renders apps.json within a minute and the plugin re-reads the file on its
own 30 s TTL. A shc config set launcherEnvironment therefore takes up
to both before a browser sees it, declared on the key’s KeyEffect so
an operator is told rather than left to guess.
8. Constraints
Section titled “8. Constraints”It is off by default on ungated apps
Section titled “It is off by default on ungated apps”The launcher axis has three values, and the shipped default is
button, which chains the middleware onto gated routers only.
ce/core/config/default.yaml:163 sets launcher: true, coercing to
button; no catalogue app declares a launcher: field.
Only launcher: auto chains the middleware onto a deployment’s open
app routes (inject_traefik.go:657-661). Under button, an ungated app
gets no injected script and /.shc/launcher/* is not served at all; the
request passes through to the app, which 404s it.
So on a default estate, everything in §6 is dormant on exactly the apps
§1 says it was built for. Whether either estate sets auto is runtime
config, not repo state.
A document may legally omit </body>, and used to lose the launcher
Section titled “A document may legally omit </body>, and used to lose the launcher”Measured on bitspur, 2026-08-16. openreplay.corp.bitspur.com serves
a 1420-byte text/html shell that ends:
</p> </div>No </body>. No </html>. Not malformed. HTML5 §13.1.2.4 makes both
end tags OPTIONAL, and html-minifier’s removeOptionalTags takes the
option. It is ordinary build output.
Both of the launcher’s injection points keyed on that tag, so both missed:
- ce’s generated rewrite is the literal regex
</body>.ReplaceAllmatched nothing, sodata-shc-launcherwas never planted. findBodyClosereturned -1, and the menu, banner and auto injectors all read -1 as “fragment: append nothing”.
Result: no button, no menu, no /apps call, no log line. The same shape
of silent absence as §1 and §7, on a third axis.
The fix is injectionPoint, which separates two questions that had
been treated as one: “where is the closing body tag” and “where does
content go”. When there is no tag, a body that DECLARES itself a
document (a doctype or an <html> opener in its first 1024 bytes) gets
content appended at its end; a body that declares nothing still gets
nothing, because that is what protects htmx and turbo partials from
having a launcher stapled into the middle of them. The rewrite injector
gets the matching fallback for the one rule shape that names the tag.
This is NOT the case-sensitivity defect (</BODY> losing the
launcher while the banner rendered), which is a different bug with a
different fix. The fallback here is gated on the plugin’s full
(?i)</\s*body\s*> grammar rather than on ce’s narrow literal, so it
fires only when NO spelling of the tag exists; the two changes partition
the problem and neither can mask the other’s regression.
What this was NOT. Three plausible causes were measured out first, and the sweep that filed this bug had the pattern backwards:
- Not the forward-auth gate, and not middleware ordering. Six
bitspur routers chain
[shc-oidc@file, shc-launcher-…]in exactly that order:midpoint,openhands,openreplay,paperless,pulp,uptime.artifacts.corp.bitspur.com(pulp) is one of them and renders the launcher fine, signed in, screenshotted. - Not the ingress omitting the middleware. Every routed host on the
estate carries its
shc-launcher-<project>middleware, gated hosts included. - Not the SPA replacing the DOM. The payload never reached the document to be replaced.
The “gated hosts never inject” bucket was an artifact of probing /
UNAUTHENTICATED: the gate answers 401 text/plain, which says nothing
about the signed-in response. agents (openhands) closes its body tag
normally and is not affected by this at all. picker is a third case
again; it ships zero HTML files and answers every path with
401 application/json, so there is no document to decorate and its
absence from the launcher is correct rather than broken.
Third-party cookies: the structural limit
Section titled “Third-party cookies: the structural limit”Step 9 requires the browser to send Keycloak’s cookie to Keycloak from inside a frame on another host. Whether that is allowed turns on whether the two share a registrable domain:
git.corp.bitspur.comframingauth.corp.bitspur.com, both underbitspur.com, same-site, cookie flows. Works.hq.flyingfoxlabs.inframingauth.corp.bitspur.com, different registrable domains, genuinely third-party. Safari has blocked third-party cookies since 2020; Firefox partitions them (a partitioned jar contains no session, because the real one was set first-party); Chrome is phasing them out.
On such a host Keycloak sees an anonymous browser and answers
login_required for logged-in users too, indistinguishable, from
inside the frame, from being logged out.
That silence is fixed, and it was never fixed only here. The payload renders its sign-in offer on any not-ok verdict the proxy did not mark UNAVAILABLE (§6; an outage or an unconfigured router still renders nothing, because there the button would be dead), so a cross-site host and a same-site host whose SSO session expired now behave identically: trigger, press, top-level login. What remains structural on these hosts is the silent check, not the launcher; no hidden frame will ever prove a user across registrable domains, so a cross-site host always pays the one click, while a same-site host pays it only when its SSO session is genuinely gone.
This is not an exotic edge case. The hidden-iframe silent check is a
standard pattern (OIDC Core prompt=none; every OIDC SPA library’s silent
renew; Keycloak’s own check-sso), and third-party cookie blocking is the
reason the industry moved off it to refresh-token rotation. SHC is meeting
a well-known wall, not a novel one.
Two things that sound like fixes and are not:
- CHIPS /
Partitionedgives the embed its own jar per embedding site. That jar has no Keycloak session in it. Wrong tool. - Related Website Sets is Chrome-only in practice, requires submission to a Google-maintained list, and caps set size, unusable where every customer brings their own domain.
The plugin acknowledges this per request: launcherSameSite
(traefik/plugin/launcher.go) compares the app host’s and the auth
host’s registrable domains (approximated stdlib-only (Yaegi cannot
import the real publicsuffix table), with both error directions of the
approximation degrading to today’s behaviour or to one extra click). On
a cross-site verdict /start short-circuits to the xs verdict page
without consulting Keycloak, which saves a doomed cross-origin round trip
on every page view. SameSite, a different mechanism, was always handled
correctly and is unchanged.
xs is now a server-side saving only. The verdict page still carries
data-shc-xs, but the payload no longer reads it: the offer is what a
not-ok answer renders, whatever made it not-ok. Dropping the read took 40
bytes out of the injected constant (10,210 → 10,170), the launcher’s
first bugfix to make the payload smaller, and it is smaller for the same
reason it is a fix. Suppressing the offer on data-shc-un (§6) put 23 of
those bytes back, for a net 10,193 against an unmoved 10,250 ceiling; the
two flags are not interchangeable, and the arithmetic is written out over
menuPayloadByteCeiling. xs was a verdict about the caller’s
topology, which the offer had no business gating on; un is the
proxy’s own health, which it must. The press behaves identically
wherever it renders: it
first attempts document.requestStorageAccess() plus a forced-silent
retry (/start?silent=1), then falls back to a top-level first-party
redirect (/start?return=<path>, the path riding the signed state).
Mixed registrable domains are the norm, not the exception
Section titled “Mixed registrable domains are the norm, not the exception”A single cluster is expected to serve hosts under several registrable domains at once. That has two consequences:
- Cross-site is a steady state, so the silent iframe should be understood as an optimisation available when the topology permits, not as the mechanism. Same-site-ness is computable per request; the plugin knows both hosts.
- No wildcard can span domains. Keycloak matches a bare
*or a trailing wildcard on a fixed host, never a*in the host segment (ce/modules/auth/forward_auth_client.go:144-146). Between*and full enumeration there is nothing.
The SSO-selector route loses the menu
Section titled “The SSO-selector route loses the menu”auth.SSOSelectorMiddleware sets appsMenu: {enabled: false}
(ce/modules/auth/launcher.go:277). Frappe’s login_path now matches
/, so on a Frappe deployment an authenticated visitor’s home page
chains the selector middleware instead of the launcher middleware and
loses the button. Known and unfixed; it is a missing button, not a broken
login.
9. redirectUris: ["*"]
Section titled “9. redirectUris: ["*"]”The launcher’s callback is per-host by construction, the set changes as
apps are installed and removed, and the gate “must complete a login for
hosts it cannot enumerate in advance”. Hence the wildcard
(forward_auth_client.go:149-151).
The mitigation the design relies on is that a code redirected to an
attacker origin cannot be redeemed without the secret the sidecar
holds. That is true, and it is thin: there is exactly one such secret,
shared estate-wide, resolved once at global scope
(ce/modules/auth/types.go:113-120). The wildcard is survivable only
because the secret holds, and the secret is itself an open owner
decision. Either alone is defensible; together, one disclosure turns the
estate into a session-theft primitive.
* also defeats cross-tenant isolation: the client exists in every
tenant realm, and a wildcard in tenant A’s realm will accept a redirect
to tenant B’s hostname.
The narrow forms are unavailable (no host-segment wildcards), so the only
alternative is enumeration, and the machinery already exists:
forwardAuthRedirectUrisJSON(extra []string) appends caller-supplied
URIs additively, with * merely hardcoded first. SHC already knows every
routed host; it writes the Traefik routers from that set.
The unsolved part is ordering: a host must exist at Keycloak before the first login through it, and route materialisation and the Keycloak reconcile run on different clocks.
10. Alternatives considered
Section titled “10. Alternatives considered”Recorded so they are not re-proposed without their costs. The first two were rejected in the original design; the rest were analysed in review on 2026-08-10 and are not formal rulings.
| Alternative | Why not |
|---|---|
| Parent-domain session cookie | Creates an ambient credential readable on every host of the parent domain, including hosts SHC does not control: strictly worse blast radius than host-only. And it structurally cannot cover an estate that routes a foreign domain. |
| Public client + PKCE in the page | The textbook silent check hands the access token to JavaScript. One XSS in one app becomes an estate token. Rejected in favour of a server-side exchange behind an opaque handle. |
| Menu rendered by Keycloak | Keycloak knows who you are, not the estate’s inventory, routed hosts, tenancy or entitlements; it would need a network path to the daemon it does not have today (verified: no extension in keycloak/ references any daemon endpoint or port). It also requires relaxing frame-ancestors on the login origin, and a cross-origin child cannot resize its own frame, so the panel could not expand without a parent script anyway. |
| Central launcher origin | One handle per estate instead of one per host is a real prize. It costs the tenant binding and the CORS refusal, which are currently free, and needs an allow-list of embeddable origins, and it makes the cross-site case worse, since the frame load, postMessage and inventory call all become cross-site too. |
Icons from the catalogue’s icon: URLs | 76 of 91 apps carry one and all 76 are third-party HTTPS URLs across 57 origins. Costs an img-src concession naming 57 foreign hosts on every app the launcher rides on, plus a beacon from each user’s browser to each vendor CDN from a page belonging to another organisation, plus link rot as the authority on how an estate looks. |
A sprite endpoint under /.shc/launcher/ | Widens the reserved namespace’s three endpoints (a security-relevant constant) for a document of a couple of KiB, and buys a second round trip and its own failure mode. Deduplicating the geometry onto the /apps response costs less on a fetch that already happens once per page view. |
| Bundled vendor logos | A trademark question with an owner’s name on it, not an implementation choice. Left as a data-only seam: the glyph table is app-name keyed, so a ruling lands as entries rather than as code. |
| Per-domain auth hostnames | Would make everything same-site again, and is what commercial IdPs call a custom domain. Collides with Keycloak 26 hostname-v2: KC_HOSTNAME pins one frontend URL and the issuer derives from it (PublicURL() + "/realms/" + realm). A second Keycloak per domain fragments the SSO session, destroying the premise. Needs its own investigation. |
11. Open work
Section titled “11. Open work”Two independently shippable pieces, in dependency order.
Cross-site detection with a click-through fallback: BUILT, and since
2026-08-11 no longer only cross-site. The plugin computes
same-site-ness per request and short-circuits the doomed framed leg on a
cross-site host. The sign-in offer it drives renders on any not-ok
verdict the proxy did not mark unavailable, and on a probe that never
answered at all (§6): the press runs a top-level redirect, which is
first-party, so
the cookie flows on every browser with no third-party-cookie dependency,
after attempting document.requestStorageAccess() plus one forced-silent
retry that keeps the silence when the browser permits it. This is what
makes the launcher work at all on a mixed-domain cluster, and what stops
it vanishing off a same-site page whose SSO session expired under a live
app session. The anti-bounce shape is guarded from both directions
(tests/unit/traefik/crosssite_test.go): no navigation without a gesture,
no tab-scoped store (the pair of properties whose naive fixes are each
other’s defects), and both directions are now driven on the same-site
verdict as well as the cross-site one.
Redirect-URI enumeration in shcd, staged so it cannot break logins:
populate extra from the routed-host set additively while keeping *,
and log any login whose redirect_uri is outside the enumerated set,
turning “can every host be enumerated in advance?” from an assumption
into a measurement. Then drop * behind a per-estate flag, then flip the
default.
Both are blocked on nothing. The wildcard’s removal is only worth doing alongside a ruling on the shared client secret, since the two risks only compound together.
12. The inventory model: the unit is the app
Section titled “12. The inventory model: the unit is the app”Design record for the inventory redesign opened 2026-08-10. Three requirements, verbatim:
- “use icons instead of names for the actual apps that are listed”
- “it shouldn’t be an app per host; it should be each one per app”
- “not even environments listed. So for multi environment … you’d specify in the config somewhere what environment the launcher’s gonna show. And then that’s all it shows.”
Everything below is either a MEASUREMENT of what ships today or is marked PROPOSED. Nothing here describes behaviour that has landed.
Why this is §12 and not a new §8. ce cites this document by section
number in six places (modules/app/inject_traefik.go,
modules/app/sso_redirect.go, modules/auth/launcher.go and three
tests all say “launcher flow doc §8”), and a handoff cites §9.
Renumbering would silently invalidate seven cross-repo references to
sections whose content did not change, so the new material is appended.
12.1 What a record is today, at each of the three layers
Section titled “12.1 What a record is today, at each of the three layers”The word “app” names a different thing at each layer, and the redesign turns on which one it means.
| Layer | Record granularity | Key | Source |
|---|---|---|---|
apps.json (the file the plugin reads) | one per (deployment, routed host) | tenant + environment + stack + host + path | ce/modules/app/apps_menu.go, BuildAppsMenu |
/api/user/effective-apps (the verdict) | one per deployment | tenant + environment + stack, with hosts[] plural inside | ce/modules/user/service.go, ListEffectiveApps |
| the RBAC grant | one per deployment, environment-blind | tenant + stack | EffectiveVerb(id, d.Tenant, d.Stack) |
| the rendered tile | one per (deployment, routed host) | the file record, one to one | renderMenuApps, traefik/plugin/menu.go |
Two facts fall out of that table and they carry the whole design.
The file is the only layer that is per-host. The verdict already speaks in deployments. So “one entry per app” does not need a new question asked of the daemon; it needs the file’s rows folded back into the shape the verdict was already answering in.
Nothing anywhere is keyed on the catalogue app. There is no grant, no
verdict entry and no route keyed on frappe. app is carried in the
file and in the verdict as a string, and ce’s own field comment says
what it is for: “the catalog app name: display metadata, may differ
from Stack when the operator named the deployment”
(AppsMenuEntry.App). Display metadata is a fair description. It is
never read as a key by anything.
12.2 stack is the axis; the deployment is the running unit; the catalog thing is an app
Section titled “12.2 stack is the axis; the deployment is the running unit; the catalog thing is an app”AppsMenuEntry.Stack is the stack axis: the name the operator
typed, what the Docker project is composed from, and what the RBAC role
stack:<name>:use names. It is unique per tenant and environment:
index.Fields("tenant_name", "name", "environment").Unique()(ce/ent/schema/deployment.go:224.) App is the app the
deployment was installed from. One app can back any number of
deployments; a deployment has exactly one app.
Reading requirement 2 as “one entry per catalogue app” and reading it as “one entry per deployment” therefore produce the same list on an estate that installs each app once, and different lists on an estate that does not. This estate does not.
12.3 ★ Three frappe benches: where the two readings disagree
Section titled “12.3 ★ Three frappe benches: where the two readings disagree”The bitspur estate runs the frappe catalogue app three times, and the
divergence is recorded in the app’s own measurements
(apps/devops/frappe/app.yaml, measured 2026-08-05 and 2026-08-10):
| Deployment host | Website Settings.home_page | disable_user_pass_login |
|---|---|---|
hq.corp.bitspur.com | unset; / is the login page | 1: no password form |
erp.corp.bitspur.com | unset; / is the login page | 0: password form present |
hq.flyingfoxlabs.in | "home"; / is a public marketing page | 1: no password form |
Same image, same app.yaml, three different sites. The restore
inventory measured different installed application sets on two of them
(scrum and frappe_keycloak on one, india_compliance on another,
apps/flagship/frappe/addons/), which is to say three
different companies’ books. And hq.flyingfoxlabs.in is a different
organisation’s own hostname, which the plugin’s payload work already
treats as a disclosure boundary: shipping that hostname inside the
injected script on another customer’s site is the leak
menuPayloadByteCeiling exists to bound (§12.8).
Collapsing those three to one tile labelled “Frappe” would ask the renderer to pick one of three links. Every choice is wrong for somebody, and one of them is wrong across an organisation boundary.
12.4 The rule: the unit is the DEPLOYMENT
Section titled “12.4 The rule: the unit is the DEPLOYMENT”PROPOSED. The tile’s identity is (tenant, environment, stack),
the deployment. Routed hosts of one deployment collapse into that one
tile. Deployments never collapse into each other, whatever catalogue app
they came from.
That is exactly the duplication requirement 2 names: “it shouldn’t be an
app per host”. A deployment answering on mail.example.com and
autodiscover.example.com produces one tile instead of two. Multi-host
deployments are first-class and operator-made; --expose is a
StringSliceVar (ce/modules/app/commands/install.go:153), so a
deployment carries as many host mappings as the operator declared, and
the plugin already records the two-host case as a live defect source:
the reason the verdict’s current flag is deliberately not read is that
“a stack answering on two hosts would … stamp aria-current on two
tiles” (traefik/plugin/menu.go:434).
The decisive argument against per-catalogue-app is not aesthetic. It
is that the entitlement model has no per-app key to collapse onto.
The verb painted on a tile comes from
verbs[verdictKey(e.Tenant, e.Environment, e.Stack)]
(traefik/plugin/menu.go:1019), and the grant behind it is
EffectiveVerb(id, tenant, stack). A user may hold stack:erp:use and
not stack:hq:use. There is no verb that describes “frappe”, so a
per-app tile either paints a verb it did not earn, paints none, or
paints the maximum across the group, and the third turns a display
change into an authorization claim.
It gets sharper. On the filtered rung resolve drops an entry the
verdict does not name. A per-app group survives if any member is
named, so grouping frappe’s three deployments and entitling the caller
to erp alone keeps the group alive and hands it a representative link
that may point at hq, an app the caller was never entitled to and,
before the grouping, was never told existed. Per-app dedupe converts
“absent” into “named, and refused on arrival”. Per-deployment dedupe
cannot: every host inside one group shares one verdict key, so the group
is entitled or absent as a unit.
Rejected, with its cost recorded: if the owner does want one icon per catalogue app, the honest form is a grouped tile: one icon that expands to its deployments when a tenant has more than one. That is a UI change inside the panel rather than a change to the inventory, and it keeps the per-deployment link and the per-deployment verb intact. It costs payload bytes (§12.8) and it is not what the siblings built.
12.5 What a tile links to when reachability and entitlement differ
Section titled “12.5 What a tile links to when reachability and entitlement differ”Rung 4 exists because those are different facts (§7), so the redesign has to say what a tile does when they diverge. Today’s answer is measured, not designed, and it is already the right one.
On the filtered rung there is no tile. resolve looks each visible
entry up in the verdict and drops the ones it does not name
(traefik/plugin/menu.go:1021). A caller standing on an app they hold
no verb on gets a panel that does not contain the app they are looking
at: no tile, no aria-current, nothing to link anywhere. Rung 4
changed which host a caller may see their list from; it did not add
the current app to the list. Preserve that: the list is what you may
open, and you may not open this one.
On the degraded rung a tile can exist without a verb. SUPERSEDED
2026-08-16: there is no degraded rung. This paragraph used to describe
a caller who was proven but whose verdict was unavailable being rendered
the whole tenant’s routed apps with an empty verb. That rung is deleted
(§7.1): an unavailable verdict now serves the caller’s last-good list, or
no launcher at all if they have never had one. A verb-less tile can no
longer arise from daemon health, only from the entitlement question
below, which is a decision made from a verdict.
The proposal that rode on it is void with it. It read: add no wire
state, because the absence of v already means “entitlement unknown” and
the response already carries state: degraded. state can now only be
filtered (menuStateFiltered is the only value that survives), so
there is nothing to key reduced emphasis off. Any future “entitlement
unknown” affordance has to be re-derived from the entitlement rungs
below, not from a health signal that no longer exists.
What must not happen is the per-app group of §12.4, because it produces the one genuinely wrong case: a tile present because a sibling deployment was entitled, linking to a deployment the caller holds nothing on. Absent is a correct answer. “Present, and refused on arrival at a deployment you were never told about” is not.
12.6 How a multi-host deployment resolves to one link
Section titled “12.6 How a multi-host deployment resolves to one link”PROPOSED, and it needs a stated rule, because two already exist and they disagree.
- The daemon’s rule.
EffectiveApp.URLis"https://" + firstHost(d.Hosts) + normaliseAppPath(d.Path)(ce/modules/user/service.go:719), andd.Hostsarrives inhost_mapping.idorder, insertion order, the order the operator declared them in. - The file’s rule.
BuildAppsMenusorts entries by(tenant, environment, stack, host, path)(host ascending, alphabetical) and the plugin preserves file order, so “the first entry for this deployment” is the alphabetically first host.
For a deployment installed as
--expose mail.example.com --expose autodiscover.example.com those two
rules name different hosts. A dedupe that keeps “the first row” would
link somewhere the daemon’s own url field does not.
The recommendation is to keep the file’s rule and say so: the surviving host is the first in the file’s existing sort, which is the lowest hostname. Reasons, in order:
- The plugin cannot see insertion order. The file does not carry it, and adding an ordinal is a file-shape change for a tie-break.
- The file’s order is already deterministic and already
content-idempotent, the property
WriteAppsMenuFiledepends on to avoid re-inoding the file every sweep. Reusing it costs nothing. - It is stable under reinstall. Insertion order is not: re-declaring
the same hosts in a different order moves the daemon’s
url, and would move the tile’s link with it.
The divergence is left standing rather than papered over, and it is
worth an owner ruling (§13): the launcher’s link and the API’s url for
one deployment can name different hosts, and nothing today says which is
canonical. The narrow fix is a primary boolean on the file record
(additive, so no version bump (§12.10)) written from the same Hosts[0]
the daemon already uses for url. That is the only form under which the
two surfaces agree by construction.
The current-tile marker is unaffected in the good case and improves in
the bad one. Current is t.entry.Host == currentHost, so a caller
standing on the non-surviving host of a collapsed deployment would
lose their aria-current. PROPOSED: compute Current as “the
request host is any host of this deployment”, evaluated before the
collapse. That preserves the invariant
TestMenuPayloadMarksExactlyOneCurrentTile pins (one tile, because
there is now one tile per deployment) and closes the case §12.4 quotes,
where two hosts of one stack both claimed it.
12.7 The environment filter, and where it is applied
Section titled “12.7 The environment filter, and where it is applied”SHIPPED, and this section’s recommendation was RULED (2026-08-11).
auto is the default. One thing changed on the way in, and it is a
consequence of the ruling rather than a revision of it: the proposal
assumed the DAEMON would resolve the filter and write a per-entry
verdict. auto cannot be written that way. The answer depends on the
request host and one apps.json serves every host, so the daemon
publishes the resolved POLICY (envfilter) and serveLauncherApps
evaluates it. Everything below about WHERE the filter runs is unchanged
and is why it runs there.
Where. Server-side, inside serveLauncherApps, in the same loop that
already narrows entries to the request host’s tenant:
for _, e := range entries { if e.Tenant == tenant { // ships today visible = append(visible, e) }}The environment predicate joins that condition. It must sit there and
nowhere later, for the reason §7 gives about the endpoint as a whole:
/apps is the only place an app list leaves the proxy, so a filter
applied in the payload script is a filter applied after the list has
already left. A client-side environment filter would ship every
environment’s hostnames to the browser and hide them with CSS, the
exact class of defect the payload’s “IT CARRIES NO INVENTORY” rule
exists to prevent.
The refusal shape does not change. An empty visible already ends in
launcherDeny(w) (a bare 401), so a filter that matches nothing
refuses byte-identically to a stranger, which is the §7 property.
What decides the value. The appsMenu block of the launcher
middleware is rendered per deployment (shc-launcher-<project>,
ce/modules/auth/launcher.go), so a new key rides the existing scoped
config cascade exactly as launcher does: deployment > stack >
environment > tenant > global. launcherEnvironment is the natural
spelling: one key with a three-value grammar, the way launcher is a
three-value mode rather than a bool plus a sibling, for the reason
already recorded there (“two keys can resolve at two DIFFERENT scopes and
compose a posture nobody authored at any single scope”).
The default is auto (ruled), and the argument that won is this. The
request host already resolves to exactly one file entry, and
menuTenantOf walks the entry set to read that entry’s tenant. The same
walk reads its environment, at no extra cost and with no extra
configuration. So:
| Value | Meaning |
|---|---|
auto (default) | show the environment of the host you are standing on |
<name> | show only that environment, on every host |
all | today’s behaviour: every environment, labelled |
auto satisfies requirement 3 on a default estate with nothing set: a
user on a prod host sees prod, a user on a staging host sees staging,
and no list mixes them. That matters more than it sounds, because of §8;
a redesign that only works once an operator sets two config keys is a
redesign most estates never see.
The label parenthetical goes away with it. Today renderMenuApps
appends " (" + environment + ")" whenever the environment is neither
empty nor default (traefik/plugin/menu.go:1083-1086). Under any filter but
all the list is single-environment, so the suffix names something every
tile shares. Requirement 3 (“not even environments listed”) is met by
deleting that branch, not by hiding it. Under all it must stay: a mixed
list with no environment on the tiles is a list where two tiles have the
same name.
12.8 What the tile shows
Section titled “12.8 What the tile shows”PROPOSED, and constrained by two measurements.
Today a tile is: the label in bold, the host and path beneath it in
grey, an uppercase verb pill when a verb is known, and aria-current on
the host match (traefik/plugin/menu.go:1315-1330).
★ The icon identifies the APP. The name identifies the DEPLOYMENT.
They are different fields and both are needed. Requirement 1 asks for
icons “instead of names”, and on an estate where every app is installed
once that reads cleanly. On this estate three tiles would carry the same
frappe icon, and only the name tells hq from erp from the
flyingfoxlabs bench. So the icon comes from App and the accessible
name comes from Stack, and the visible name is the thing that may be
demoted (to a caption under the icon, or to a tooltip), never removed.
A tile whose only content is an icon has no accessible name at all,
which fails the disclosure pattern the panel already implements
(role="dialog", aria-label, aria-current).
The icon now HAS a wire path. AppsMenuEntry carries an icon
field as of ce feat/launcher-app-icons-ce; EffectiveApp still does
not. The addition is additive and carries no version bump, exactly as
§12.10 requires. The full contract is §12.8.1.
★ And every icon in the catalogue is a third-party URL. Measured on
shc origin/main 2026-08-10:
| count | |
|---|---|
| catalogue apps | 91 |
declaring icon: | 76 |
| declaring a local icon | 0 |
| distinct remote origins referenced | 57 |
The 15 with no icon are almost entirely things that would never carry a
tile: three test fixtures, five bridge and plug packages, and seven
storage or backing-service packages. The other 76 point at
about.gitlab.com, upload.wikimedia.org,
raw.githubusercontent.com, supabase.com and 53 more.
Rendering those as <img src> inside the panel has four consequences,
and the first is the one that matters:
- It re-creates the disclosure the payload work removed. The
injected script is a constant precisely so that it carries no
inventory. A panel that fetches 57 third-party origins announces the
estate’s app list to those origins, per user, with the app’s own
hostname in the
Referer, including onhq.flyingfoxlabs.in, where §12.3 already establishes that one customer’s estate detail on another’s page is the leak class in question. Tile images are inventory leaving the proxy by referral instead of by response body. - CSP. An app serving
img-src 'self'renders 76 broken images. The plugin’s CSP cooperation path merges a script hash and two frame origins today; merging 57 image origins into another app’s policy is a widening of a different order, and it would have to be computed from the inventory, which makes a security header a function of the app list. - Air-gapped and offline estates render nothing.
- Availability. A remote logo that 404s is a broken tile no estate operator can fix.
The recommendation was that icons are proxied or embedded, never
hot-linked, and THAT IS WHAT SHIPPED. The daemon fetches each icon
once, server-side, normalises it and writes it beside apps.json on the
license mount, the same materialised-file doctrine the menu already
uses, and the same “no outbound HTTP from the plugin” rule. A tile with
no icon still falls back to the category glyph or the generated
monogram, which is the common case and not an error branch. Hot-linking
was never on the list and is not on it now. See §12.8.1.
The byte budget, measured, because it binds the icon work:
| State | payload bytes | ceiling | headroom |
|---|---|---|---|
shc main today | 7,195 | 8,192 | 997 |
| with §11’s cross-site fallback | 8,246 | 8,704 | 458 |
(TestLauncherPayloadStaysCSPAndDOMSafe reports the served size; the
ceiling and its rationale live in menu_test.go.) The ceiling bounds the
injected script, not the JSON response, so an icon URL per app costs
response bytes, which are bounded instead by maxMenuEntries = 60 and
are not gated. The <img> construction, its sizing and its error
fallback are script bytes, and after the cross-site fallback lands they
have 458 bytes to fit in. Raising the ceiling again is permitted and is a
decision that has to be written down where the constant is; the point of
recording the number here is that a third raise in one month is a signal
about the payload, not about the guard.
12.8.1 The icon pipeline as built: the same-origin contract
Section titled “12.8.1 The icon pipeline as built: the same-origin contract”LANDED in ce feat/launcher-app-icons-ce (core/appicon,
modules/app/launcher_icon.go, daemon/services_seams_app_icons.go).
This section is the interface between the two repos; §12.8 above is the
reasoning that produced it.
The shape of the answer. The browser never learns a vendor URL. Each
package ships a local icon.svg / icon.png beside app.yaml. The
daemon stamps icon: "icons/<sha256>.<ext>" onto the apps.json entry,
named by the hash of the bytes, and materialises them at
<licenseDir>/icons/ under that name. The Traefik plugin prefers that
stamp, then the category glyph the daemon stamps from the package’s
category:, then a monogram. /apps names each picture by content name
plus a URL on the plugin’s icon door (SHC-3519); until then it carried
every picture as a data: URI, 635 KB at the entry cap, uncached. No
foreign img-src origin is named, no vendor CDN is told who is looking,
and an air-gapped estate draws the same tiles as a connected one.
The things the plugin side codes against:
| wire key | icon, on each apps.json entry, omitempty |
| value | "icons/<sha256>.svg" or "icons/<sha256>.png", the lowercase hex sha256 of the bytes. A relative reference the plugin matches (menuIconRefRe) before joining. Never a URL, never bytes. The plugin still reads a v0.1.21 daemon’s "icons/<app>.<ext>" and names the URL by the hash of its bytes, so an estate upgraded in place keeps its pictures before the upgraded daemon’s first sweep. |
| bytes | <licenseDir>/icons/<sha256>.<ext>, a sibling directory of apps.json, inside the same already-bind-mounted read-only licence directory. A changed icon is a new name. The daemon prunes a file once two writes in a row have not referenced it, so a plugin still holding the previous apps.json (30 s TTL) keeps finding its files. |
| content types | exactly two, forever: image/png and image/svg+xml |
on /apps | each tile’s a is the content name; arts[name] is /.shc/launcher/icon/<name>?k=<key> |
| the key | k = base64url(HMAC-SHA256(gate state secret, "shc-launcher-icon\0" + sha256 hex))[:16 bytes]. Only /apps hands it out, so only a caller whose inventory carries a picture can fetch it; without it, anyone holding a catalogue icon’s public bytes could ask which apps the estate runs. |
How the icon door serves them, and every clause is load-bearing:
- Match the name against
^[0-9a-f]{64}\.(svg|png)$before joining it to the directory. No.., no extra slash, no uppercase, no third extension.launcherIconHashis the plugin’s copy of that rule. - Check the key first, in constant time, before touching the disk. A malformed name, a missing or wrong key, an absent file and bytes that do not hash to their name all answer the same bodyless 404, so the door cannot tell “not on this estate” from “wrong key”.
- Re-hash the bytes and refuse a mismatch: the answer is cached for a year.
- Decide the
Content-Typefrom the extension, by table lookup. Never sniff. The set is closed at two, so there is no default branch. - Send
X-Content-Type-Options: nosniff,Content-Security-Policy: default-src 'none',Cache-Control: public, max-age=31536000, immutableandETag: "<sha256>"; answerIf-None-Matchwith a bodyless 304. - Reference the bytes from
<img src>, a CSSbackground-image, or<object>; never inline the SVG into a live DOM. An SVG in an image context cannot run script or load subresources; that is a browser guarantee and it is the strongest fence in the stack. Inlining switches it off. The sanitiser is the second fence, not the only one. - On a page whose own CSP constrains images, the injector appends
https://<host>/.shc/launcher/icon/toimg-src(or synthesisesimg-srcfromdefault-srcplus it). Nothing the app listed is removed,img-src 'none'is never widened, and a policy that already admits the path ('self',*, the host) is left byte-identical.
★ EMPTY MEANS “DRAW THE GLYPH, THEN THE MONOGRAM”. Not an error, not
a retry, not a placeholder. The app declares no local icon:, or the
file failed a cap, or the daemon predates the stamp. Category glyphs
are a last resort (they collide by construction); a letter tile on a
known catalogue app is a sourcing miss.
What the daemon guarantees about the bytes. Sniffed on content, not
on the vendor’s Content-Type; rasters decoded and re-encoded as PNG
(which is what strips EXIF, ICC, tEXt and any trailing appendix; only
pixels survive); SVG rebuilt from an element and attribute allowlist
with no script, no event handlers, no external references, no foreign
namespaces and no DOCTYPE internal subset; capped at 256 KiB fetched,
64 KiB stored, 192 px on a side (3x DPR for a 64 px tile), and 8192 px
on any declared extent so a decompression bomb is refused before it is
allocated.
Where the fetch happens, and where it must never happen. The
clusterfs licence section (modules/app/license_section.go), over the
DEPLOYED set, not at crawl time, because a crawl
walks the whole 91-app catalogue and runs at boot on every node that
ships app roots, which would dial 56 vendor origins per node per
restart for icons no tile will ever draw. No launcher request path
ever triggers an outbound call, and rendering the menu is a map lookup
and a stat.
The failure budget is stated, because it is large. Measured against
the live catalogue on 2026-08-11: of 67 distinct icon URLs, 29
produced an icon (16 PNG including all six live .ico favicons, 13
SVG) and 38 were refused: 36 of them vendor 404/403, one 288 KB of
HTML served under a .svg URL with a 200, one over the byte cap. Link
rot is not the edge case here, it is 45.6% of the population. Every
refusal emits X200980ICNFCH naming the app, the URL and the reason,
and is persisted with a 24-hour retry clock in
<StateHome>/appicons/ledger.json, which is deliberately outside
the licence directory, because that directory is an interface and the
ledger is bookkeeping. Without that persisted negative cache a 60-second
sweep would beacon three dozen vendor CDNs every minute forever, which
would be a worse leak than the one this design closes.
Byte cost on the payload: zero. The value is a name in the JSON
response, which is bounded by maxMenuEntries and is not gated. The
<img> construction is script bytes and is the plugin side’s budget to
spend against menuPayloadByteCeiling.
Section titled “Byte cost on the payload: zero. The value is a name in the JSON
response, which is bounded by maxMenuEntries and is not gated. The
<img> construction is script bytes and is the plugin side’s budget to
spend against menuPayloadByteCeiling.”12.9 Why the dedupe cannot leak an app across tenants
Section titled “12.9 Why the dedupe cannot leak an app across tenants”This is a security property, so the argument is stated rather than asserted.
The dedupe operates on a set that is already single-tenant, and that
is a property of its input, not of its key. In serveLauncherApps the
order is fixed:
menuTenantOf(entries, reqHost)resolves the tenant from the file; an unrouted host resolves to""and refuses before any daemon call.- A proven identity whose tenant differs from the host’s tenant is refused outright.
visibleis built by exact match,e.Tenant == tenant.- Only then is
resolvecalled, and it is called withvisible.
A grouping function applied to a single-tenant slice cannot emit a cross-tenant group, whatever it groups on. The property therefore survives the redesign under one condition, which is the invariant the implementation owes:
The dedupe runs downstream of the
e.Tenant == tenantfilter, never upstream of it, and its group key includes the tenant.
Both halves are load-bearing, for different reasons. The filter is what
makes the property true today. The key is what keeps it true after the
next refactor moves the grouping: a key of (app) alone, or of
(environment, stack), is one edit away from being applied to entries
instead of visible, and at that moment a group would span tenants and
its surviving representative could carry another tenant’s hostname. This
document’s own doctrine is that a guard should not depend on the order of
the code preceding it.
★ The caller who makes this concrete is the platform admin.
visibleDeployments returns ListAll (every tenant’s deployments) for
a platform admin (ce/modules/user/service.go:593-595), so a platform
admin’s verdict genuinely names every tenant on the estate, and
verdictNamesTenant passes on any host they stand on. The only thing
that narrows their rendered list to the host’s tenant is step 3. It is
not a redundant check with the verdict as a backstop; for that one caller
it is the whole boundary. Anything that reorders the pipeline so grouping
precedes the tenant filter renders one tenant’s app list on another
tenant’s host, to the estate’s most privileged user, silently.
Two smaller notes, both preserved by that rule:
- The verdict cannot widen the list.
resolveiteratesvisibleand looks each entry up in the verdict, never the reverse: “an app the verdict names but the file does not route for this tenant is simply not here to answer” (menu.go:1015). Collapsing hosts withinvisibledoes not change the direction of that lookup. - The environment filter of §12.7 narrows only. It is applied in the same loop and can never admit an entry the tenant test rejected, because the two are a conjunction on one record.
12.10 Constraints the implementation inherits
Section titled “12.10 Constraints the implementation inherits”No version bump on apps.json, deliberately. The file contract is
explicit: new needs are met by ADDING fields, which the plugin ignores
when it does not know them, “never by bumping”, because a bump
dark-fails the menu on every already-deployed image until every Traefik
on the estate is rolled (traefik/plugin/menu.go, the menuFile
contract block). An icon field and a primary flag are both additive
and both legal. Reshaping the record to nest hosts under a deployment is
not. That is exactly the incompatible reshape the version guards,
and it would blank the launcher estate-wide for the length of the roll.
The same rule binds the wire response: launcherAppsFormatVersion = 1,
and “the script refuses any other value, so a future reshape dark-fails
to ‘no menu’ on an un-rolled image”. The plugin and the payload ship in
one image, so that pair moves together, but only with the image.
Yaegi. The plugin is interpreted, not compiled, so anything added to
it lives inside a restricted stdlib; a sibling lane measured os/exec as
unresolvable. Yaegi also honours only the legacy // +build line and
ignores a lone //go:build, so a file guarded the modern way is silently
included.
Any edit under traefik/plugin/ diverges the tree from the image ce
pins, which the traefik-plugin-pin arch-fitness rule refuses,
reddening both make lint and make test/unit, until a rebuilt image
is repinned in ce. Measured, and proven by the revert of §11’s cross-site
work on shc main (89a0067b4). The plugin-side and daemon-side halves
of this redesign therefore have different landing costs and belong in
separate commits.
12.11 Is any of this visible? Read §8 first
Section titled “12.11 Is any of this visible? Read §8 first”On a default estate, no.
The shipped default is launcher: true
(ce/core/config/default.yaml:163), which coerces to button, which
chains the middleware onto gated routers only; no catalogue app
declares a launcher: field. Under button an ungated app gets no
injected script and /.shc/launcher/* is not served at all; the request
passes through to the app, which 404s it.
So on the apps §1 says the launcher was built for (every app carrying
its own native SSO, which is every app deliberately left ungated) this
redesign changes the appearance of a panel that is not rendered. It is
visible on gated routes, where the flow was never broken, and on
launcher: auto deployments, which are runtime config that no repo state
records.
This does not make the redesign wrong. It makes launcher: auto a
prerequisite for observing it, and it means “we changed the launcher
and nothing looked different” is the expected result on a default estate
rather than evidence of a defect. Whether either estate sets auto
should be measured before the work is judged; the arming decision is
listed in §13.
13. Open questions this redesign raises
Section titled “13. Open questions this redesign raises”RULED 2026-08-11. The owner answered every question in this table.
The Ruling column is what shipped; the recommendation is kept beside it
because two of them were overruled and the reasoning is worth reading
next to the answer.
| # | Question | Recommendation | Ruling (2026-08-11) |
|---|---|---|---|
| 1 | An app exists only in staging while the launcher shows prod: hidden, or shown as a fallback? | Hidden. “That’s all it shows” is unambiguous, and a fallback makes the list a function of what else happens to exist, so two estates with identical config show different environments. Staging hosts are also the ones carrying debug flags and seeded data, and a fallback surfaces them precisely when nobody has reviewed them. The escape is launcherEnvironment: all, or auto (§12.7), under which a user standing on the staging host sees staging. | Not re-opened: the escape is all, and the shipped default auto shows a staging host its own staging apps. |
| 2 | Two deployments of one catalogue app: per-app or per-deployment? | Per-deployment. Entitlement has no per-app key (§12.4), this estate has three frappe benches holding three organisations’ data (§12.3), and per-app grouping resurrects entries the verdict dropped (§12.5). If the owner still wants one icon per app, take the grouped-expanding tile, not a collapse. | Per-deployment, on the key (tenant, environment, stack). Confirmed: the three frappe benches must each stay reachable. |
| 3 | The launcher’s link and EffectiveApp.URL can name different hosts for one deployment (§12.6). Which is canonical? | Add a primary flag to the file record, written from the same Hosts[0] the daemon uses for url. Until then the launcher uses the file’s existing sort and the two can disagree. | primary landed, and is not sufficient. Terraform sorts routes, so <name>-api always precedes <name>; the per-host role marker (app.yaml host_roles:) is consulted BEFORE order. §7. |
| 4 | Icons: proxied through the daemon, or a generated monogram? | Proxy or embed. 76 of 91 icons are third-party URLs across 57 origins (§12.8); hot-linking re-creates the payload disclosure and breaks under img-src 'self' and offline. Monograms ship with no fetch at all and are the cheaper first cut. | Category glyphs + monogram fallback. NO VENDOR LOGOS: a trademark question with an owner’s name on it, not a lane’s. The launcherAppCategory seam stays app-keyed so a later ruling is a data change. |
| 5 | Does the visible app name survive next to the icon? | Yes, as the accessible name at minimum. Three frappe tiles share one icon and are told apart only by name (§12.8). | Only where two tiles in the answered list share an icon. Not unconditional, and no ceiling raise for it: the collision is decided server-side over the whole answer, and a tile whose glyph is unique carries no caption at all. |
| 6 | launcherEnvironment default: auto (the host’s own environment), or unset meaning all? | auto. It satisfies requirement 3 with nothing configured, which matters because of §8. | auto. Recommendation accepted. It moved the filter’s evaluation from the daemon to the proxy; a boolean cannot hold a per-viewer answer. |
| 7 | Raise menuPayloadByteCeiling a third time for icon rendering? | Decide after the cross-site fallback lands and the real cost is measured against its 458 remaining bytes. Do not raise it speculatively. | No. The ceiling is untouched at 10,250; the payload was 10,210 when this was ruled (10,193 today; see menuPayloadByteCeiling). The caption’s 199 bytes were paid out of a 213-byte minification, not borrowed. |
| 8 | Is launcher: auto set on either estate? | Repo state cannot answer it (§12.11). Measure before judging the redesign. | Unchanged, still a measurement owed against a live estate, not a repo question. |
Q5 OVERRULED 2026-08-13: every tile always shows its stack name,
iPad-style. The sparse policy the 2026-08-11 ruling shipped (“only
where two tiles share a mark; monograms never captioned”) was correct
about pictures and wrong about the reader. A launcher where only SOME
tiles are named teaches that a name is a warning sign, and the
identification question was still being asked one hover at a time on
every tile the policy left bare. What replaces it: the server
(captionEveryTile) middle-ellipsizes a long name to 14 runes
(middle, not end, because estate stack names differ at both ends
(gitlab-s3, huly-nextcloud, <name>-api)) and the payload paints
a.m||a.n unconditionally, with the full name still on the tile’s
title/aria-label. The payload got 5 bytes SMALLER (10,323 → 10,318;
always-on needs no conditional) and the wire pays only for names long
enough to shorten, so neither ceiling in Q7’s ledger moved.
14. The trigger’s position
Section titled “14. The trigger’s position”The floating trigger is draggable, and where it ends up is a dock rather than a coordinate.
Eight docks: three rails, three stops, minus one. Left, centre or right, crossed with top, middle or bottom. Release snaps to the nearest, always: the rail is which third of the viewport the trigger’s centre is in, the stop is the nearest of the three. There is no magnet radius and no free placement, so a drag that ends off-screen is not representable.
Two crossings are not docks:
- Dead centre (centre rail, middle stop) is refused outright. It parks an opaque control in the optical middle of somebody else’s content, the one position from which the trigger obscures something no matter what the page is.
- Bottom-centre below 600px is refused, and §14.1 is why.
The centre rail was added in SHC-235, over a design that had deliberately left it out: “top-centre is the notch, the dynamic island and every app’s own header bar; bottom-centre is the home indicator, the browser’s toolbar and every mobile tab bar.” Every one of those hazards was real. Each is now answered by a mechanism rather than by omission: the safe area writes for the notch and the home indicator, the collapse for the header bar, and the width gate for the tab bar.
The encoding is additive, not visual. DX is 0=left, 1=right, 2=centre. Centre was appended rather than inserted, because renumbering
to left/centre/right would silently relocate every existing user’s
trigger from bottom-right to bottom-centre on their next page load, on
every host. The payload carries reading order as a string ('021') where
the keyboard walk needs it.
14.1 The collapse, and the width gate
Section titled “14.1 The collapse, and the width gate”Nothing may be obscured at a centre stop. There are only two ways to
honour that, and one of them is unavailable: the launcher may not write
padding onto a third party’s <body>, because that mutates the layout
of an application this repo does not own and cannot test; it breaks
pages whose scroller is an inner element, and double-counts against apps
that already reserve their own safe-area band.
So the trigger collapses. At a corner it is 52×52 floating 16px inside the safe area, a 68px band. At a centre stop it is 52×26 flush against the safe area, a 26px band, 62% less of the page’s own edge, in the shape every platform already uses there: a half-height tab rather than a floating puck. The tap target keeps its full 52px of horizontal travel; collapsing further to a hairline grabber was refused, because a 12px target on chrome injected into every page is a worse defect than the collision it dodges.
The collapse shrinks the bottom-bar collision; it cannot delete it. A bar and a control docked to the same edge at the same horizontal midpoint share a band, and no geometry available to the payload changes that. So bottom-centre is gated on viewport width: offered at 600px and above, refused below. SHC-215’s mobile bottom bar (search, video, bell, calendar, avatar) is mobile-only by its own design, so a dock that cannot exist below 600px cannot collide with a bar that does not exist above it: structurally impossible rather than merely unlikely, and without the plugin and that soft-fork patch series having to agree about a number. The alternative (reading SHC-215’s computed bar height across repos and docking above it) was refused as cross-repo coupling re-verified on every upstream bump.
Top-centre is not gated and is live at every width. A phone gets seven docks, a desktop eight. The gate is read at every decision, never cached, so a rotation into landscape past 600px makes bottom-centre reachable and a rotation back refuses it: no resize listener, no stale flag. A stored bottom-centre read on a narrow viewport fails the same legality check the snap applies and is treated as absent, landing the trigger on its default dock rather than somewhere the snap cannot reproduce.
The default dock is width-gated too (SHC-969). At 600 device px and
up a first-time visitor’s trigger starts bottom-right, as it always has.
Below that it starts on the right rail’s middle stop. A phone pins its
primary actions to the bottom band: a bottom sheet’s footer, a dialog’s
Create, a snackbar’s Undo, Material’s FAB 16px in from the same corner.
Those are fixed, so no scroll moves them out from under the puck, and
mpo’s filter sheet put Apply exactly there at 375px. The middle of the
edge holds scrolling content instead, and it is where AssistiveTouch
rests. The gate is the one leg() reads, in device pixels. A stored
dock is the user’s choice and wins at every width.
Why discrete. A free position has to be persisted as pixels, and a
pixel does not survive a rotation or a collapsing URL bar; yesterday’s
y is off the bottom of today’s viewport or under the home indicator. A
dock re-resolves at every viewport size and is two characters of storage.
Each docked side is written twice through the CSSOM: a plain gutter, then
the same gutter plus env(safe-area-inset-<side>). An engine that cannot
parse the second declaration discards it and keeps the first, so the
fallback needs no feature test. env() is zero on a page that never
opted into viewport-fit=cover, which is correct: such a page is
letterboxed and its layout viewport already excludes the unsafe area.
Position persisted on the daemon, keyed by the user, until FZ-8531.
It used to live in localStorage, per host, on three arguments: that
per-app was the
honest scope; that there was no write path to anything durable at any
layer; and that a mutation under /.shc/launcher/ would mean designing
CSRF for the estate’s most widely-exposed surface. The last two were
answered by §21.6’s layout lane, which built exactly that write path
behind a four-rung ladder. The first was overruled by the owner in the
same terms he overruled tile order: pinning is per user. On reflection
it was always a good argument for a per-app override and a poor one
for having no estate-wide value at all; what a user wants is “my
launcher lives at the top middle”, stated once, everywhere.
It rides the layout blob, and costs the daemon nothing. The dock is one more field on the arrangement the launcher already stores:
{ "v": 1, "k": "20", "d": [], "p": [["cloud", "mail"]] }The daemon validates json.Valid and a 16 KiB cap and stores the bytes
verbatim in a json.RawMessage; it has no schema for the inside of the
blob and never unmarshals it. So an estate running today’s daemon serves
the dock correctly the moment the new plugin ships: no ce change, no
pin bump, no daemon roll for this half. A second daemon route would
have been a schema, an API, an authz story and a migration for two
characters; a sibling key in the request body would have been a ce change,
because that struct is typed and an unknown sibling is dropped.
localStorage wins, the stored dock seeds. On load the dock is
read from the stored arrangement directly, never from the merge, and is
used only when this origin’s localStorage holds no dock. localStorage is
still written on every move, immediately and unconditionally, and is
what positions the trigger whenever it holds a dock. The daemon leg is
debounced at 400ms, but app hosts get no write token since FZ-8531, so
it never fires and a move stays on the host it was made on.
Two paths have no layout machinery at all and degrade to localStorage
silently: the cross-site sign-in trigger (no panel, no inventory, no
token) and the subscribe pane. A cookie remains strictly worse than
either: host-only too, so it solves nothing, and it rides every request.
A tap is still a tap. Nothing moves until the pointer has travelled
8 CSS px (Android’s and Chrome’s own touch slop), scaled by the same
legacy-viewport factor K as everything else, so a phone rendering a
viewport-less page at 0.4× gets the same physical threshold.
touch-action: none on the 52px trigger is the whole answer to fighting
the scroll: the browser stops claiming gestures that start there, so the
pointermove stream is never stolen mid-drag, while the page still
scrolls from every other pixel. The drag also owns the trigger’s click,
because a drag ends in a click on every browser and a launcher that opened
on click alone would fling the panel open every time it was moved; the
synthetic click a keyboard Enter or Space produces still passes.
The panel is unaffected, and that is worth stating because it sounds
like it should not be. The dialog is full-viewport (§ the owner’s four
requirements), not a popover anchored to the trigger, so there is no
expansion direction to follow and no dock that can aim it at a page’s
primary control. show() also hides the trigger for as long as the panel
is up, so a top-right dock cannot put it over the dialog’s own close
control. The recorded “panel covered Penpot’s login form” defect was the
panel being stuck open (an app’s display rule beating the hidden
attribute) and is answered by the shadow root and by the pane carrying
its own inline display, neither of which positioning touches.
Keyboard. A drag-only control is inaccessible, so the arrow keys walk the docks whenever the trigger has focus, and they are installed before the Pointer Events check: an engine with no pointer support keeps a trigger that taps and a trigger the keyboard still moves. The accessible name never changes (it is what a screen-reader user navigates by) and nothing is written to storage until the user chooses.
The cross-site sign-in trigger shares all of it. On a host where the
silent check cannot run (§8), the offer’s button is the launcher icon
the user sees (same factory, same mark, same corner), so it drags on the
same eight docks and reads the same stored position. A user who moves it
to sign in finds the menu’s own trigger in the place they left it. What
it does not share is the daemon leg: there is no inventory on that path
and therefore no token, so its dock is localStorage only, exactly as
every dock was before SHC-235.
The frame self-disable (W.top !== W.self) is untouched. Positioning now
declares two IIFE-level slots (the dock value and the save hook that
carries it between the trigger and the panel), and both sit after the
guard, so a framed document returns before either initialiser runs.
The stored key is shc-dock, and it is the one tab-scoped key the payload
is allowed to touch. tests/unit/traefik enforces that by NAME: the probe
harness reports every key read or written and the guards refuse any key
not declared with its reasoning. The rule being enforced is not “the
payload may not use storage” but “nothing persisted may suppress the
silent identity check”; shc-dock is read while building the menu, after
an inventory has already been served, and is never consulted on the probe
path. A returning suppression latch is a new key, and it fails naming
itself.
15. Tiles open a new tab
Section titled “15. Tiles open a new tab”Pressing a tile opens the app in a new browsing context. The page the user was standing in is never taken.
The mechanism is the anchor’s own, and that is the whole design. The
tile has always been an <a> with an href; it now also carries
target="_blank" and rel="noopener", and nothing intercepts the
activation. The two alternatives were both rejected on defects rather
than on taste:
| mechanism | why not |
|---|---|
W.open() from a click handler | needs preventDefault to avoid opening twice, and preventDefault kills every modifier gesture below. It is also a programmatic popup, blocked outright wherever the click is not recognised as a user gesture. |
href plus a rewritten handler | the worst of both, and more bytes than either. |
Because the browser performs the activation, middle-click, ctrl/cmd-click,
“open link in new tab”, drag-to-tab-bar and copy-link all keep working,
and a modifier-click opens exactly one tab rather than two. That last
property is invisible to a plain left click and is the one a hand test
never finds, so it is a guard
(TestLauncherModifierClickOpensExactlyOneTab) with a mutation proof
beside it.
rel="noopener" is the security half and it is not redundant. A
context opened with target="_blank" would otherwise receive a live
window.opener handle back to this document. Any script in the opened
page could then call opener.location = … and silently replace the page
the user believes they left open: reverse tabnabbing. The launcher lists
an operator’s whole estate, so both pages look trusted to the user, which
makes the swap worse rather than better. Modern engines imply noopener
for target="_blank" (HTML spec, ~2021), but this payload lands on
whatever browser the visitor brought: Safari before 12.1, legacy Edge and
every embedded webview predating the change do not imply it. Stating
it costs 17 bytes. noreferrer is deliberately not added. It would
also strip the Referer header, and the default referrer policy already
sends origin-only cross-origin, so those bytes buy nothing the threat
model asked for.
The panel closes on activation. The dialog is full-viewport (§14, and
the owner’s four requirements), so a tile that opened a tab and left the
dialog up would hand the user back a page covered by a menu they had
already finished with, on every return to that tab, forever. Closing
uses shut(), the same function Escape and the close button call, so
there is one close path rather than three; the trigger comes back at
whatever dock the drag left it on and nothing about positioning is
touched. It is assigned as an ordinary onclick with no
preventDefault, which is what keeps the single-open property: the
navigation is still the browser’s. A middle-click fires auxclick rather
than click, so opening a background tab correctly leaves the panel up,
which is what a user opening several apps in a row wants.
The current tile is not a special case. The tile carrying
aria-current="page" opens a new tab like every other one. “Always” was
the requirement, and an inventory whose current entry quietly navigated
in place would be the one tile that still takes the page out from under
the user.
It is announced. A control that opens a new context must say so, and
an icon-only tile has nowhere to say it except its accessible name, so
aria-label and title both become <app>: <verb> (opens in new tab).
Extending the name rather than adding a caption is deliberate: visible
text is exactly what the icon redesign removed, and it costs payload
bytes the ceiling no longer has (§ menuPayloadByteCeiling, 26 B of
headroom).
The guards run the payload rather than reading it
(launcher_newtab_node_test.go): the harness dispatches a real click,
lets the payload’s handlers prevent or not, and then models what a
browser does next: open a context, recording whether that context
would receive an opener handle, or navigate the current document. A
string match could not tell any of those apart.
16. One tile per stack name: environment precedence
Section titled “16. One tile per stack name: environment precedence”The owner’s rule (2026-08-13), verbatim intent: “if more than one deployment is supposed to show up in the launcher it will just show the first one by order of environment precedence. environment precedence is a config that exists only on the tenant and global scope that lists the precedence of environments. by default: production, prod, default, test, dev etc. if it’s not in the list then it’s at the end by alphabetical order of the environment name.”
The environment name is prod. The shipped default ranks it first.
The name production is refused at deployment input, with an error naming
prod.
The mechanism is a third collapse, downstream of the other two. The
envfilter (§7) decides which environments QUALIFY; dedupeMenuTiles
collapses the routed hosts of one deployment; dedupeMenuEnvironments
(traefik/plugin/menu.go) then collapses the qualifying deployments of
one stack name (group key (tenant, stack), the tenant half being
§12.9’s invariant) down to the single one the precedence order ranks
first. Under the shipped envfilter default (auto) the answer is already
single-environment and the collapse is a no-op; it earns its keep under
all and under an un-rolled daemon’s empty policy, the two states where
one stack used to draw two tiles.
The contract, shared with the console and ce. Do not let the three drift:
| config key | launcher.environment_precedence, tenant and global scope only; tenant replaces global, global replaces the built-in default |
| default order | prod, live, staging, stage, default, test, qa, dev, development |
| comparator | listed names by list position; unlisted names after every listed one, alphabetically. Exact, case-sensitive match. (The console’s resolveEnvironmentOrder folds case before matching; on daemon-written lowercase names the two readings agree byte for byte.) |
| wire | envprecedence on each apps.json entry, omitempty; the daemon stamps the RESOLVED list per entry, the same policy-stamping pattern as envfilter, read off the request host’s own entry for the same reason (§7) |
| absent | the built-in default order. An un-rolled daemon still collapses (by the order every surface ships anyway), which is the honest degradation: the collapse keeps one tile per stack name whatever the order, so nothing can vanish outright. |
The comparator exists three times on purpose (the console’s
resolveEnvironmentOrder (features/console/src/launcher/precedence.ts),
ce’s ResolveEnvironmentPrecedence / CompareEnvironments helpers
(ce/modules/app/launcher_precedence.go), and the plugin’s
menuCompareEnvironments) because the plugin is interpreted by yaegi
and can import neither. Keep the semantics in lockstep; the code cannot
be shared.
What the collapse must never do, each pinned by a test in
menu_inventory_test.go:
- Resurrect a deployment the verdict dropped, or hide the one it
kept. It runs downstream of
resolve, so it picks among deployments THIS caller may open: a caller entitled to staging alone still gets staging, whatever the list prefers. The §12.5 defect (a tile present because a sibling was entitled) stays impossible. - Carry a verb or
currentacross the collapse. Every group member is a DIFFERENT deployment, so the loser’s verb is an entitlement on an app the answer no longer names, and itscurrentmarks a page the surviving tile does not link to. A caller standing on a collapsed-away environment gets no current tile, the same answer the envfilter gives a host in an unlisted environment. - Delete the loser. Clay’s 2026-08-14 ruling put extra environments
on the surviving tile’s right-click menu (
k, kinde). The kid is a link to the loser’s host, not an entitlement badge. - Group across tenants. The group key includes the tenant, and the
collapse runs downstream of the
e.Tenant == tenantfilter, both halves of §12.9’s invariant, restated because this is the second function the invariant now binds.
The daemon stamps envprecedence since ce 2201a88f. BuildAppsMenu
(ce/modules/app/apps_menu.go) resolves
launcher.environment_precedence once per tenant (tenant row > global
row, via ResolveEnvironmentPrecedence) and stamps the resolved list
verbatim on every entry of that tenant, the same policy-stamping pattern
as envfilter. When no row is set at either scope it stamps nothing and
the plugin applies the built-in default order above, which is also what
an estate behind an un-rolled daemon gets. One wire corner, recorded on
launcherEnvironmentPrecedenceForTenant: the field is omitempty, so an
explicit empty list (“no preferred order”) rides as absent and the
plugin falls back to its default, while the web console, which reads the
config key directly, honours it.
17. Placement: launcher_placed and launcherPlaced, both halves real
Section titled “17. Placement: launcher_placed and launcherPlaced, both halves real”Whether a deployment is a launcher DESTINATION at all. Two halves, one
axis, both shipped as of ce 4a67b0c5:
- The app.yaml half:
launcher_placed: false, top level, bool grammar (ce5ceafded). A property OF THE APP: an app whose routed host exists to be called rather than opened (the measured case that forced the key wasnextcloud-picker; that sidecar now usesbelongs_toso it can ride Nextcloud’s menu, and the remaining declarer isgitlab-huly, a webhook with no page) declares it at package time, the same argument that puthost_roles:in the catalogue. Absent means placed. - The scoped config half: the
launcherPlacedkey (ce4a67b0c5), the operator override: resolved per deployment through the five-tier cascade likelauncher/launcherGzip, and a row at ANY scope wins over the app.yaml default in both directions:falseunplaces an app the catalogue placed,trueplaces one the catalogue opted out. Absent everywhere means placed. Bool grammar only; the value domain refuses anything else atshc config settime (thelauncher ondefect, pre-empted), and a pre-declaration typo row degrades to the app default rather than moving a tile.
The wire: stamped, never dropped. The first ce cut (5ceafded)
dropped an unplaced deployment’s entries from apps.json outright.
That was retired the day the config half landed, because the file is
ALSO the authority menuTenantOf resolves “which tenant owns this
host” from; a dropped entry cost the unplaced app’s own pages their
injected launcher and answered its host a bare 401, an outage wearing
a preference’s clothes (the same argument that keeps envfilter-excluded
entries in the file, §7). So BuildAppsMenu now stamps the entries:
| wire key | placed, on each apps.json entry, omitempty |
| value | false is the ONLY value ever written; placed rides as an absent field, so an estate that never touches the axis produces byte-identical files |
| plugin side | filter unplaced entries with no parent out of the LIST; sidecars that belongs_to a parent still reach foldMenuStack so they can ride that tile’s menu (§20). Tenant resolution still sees every entry |
| absent | placed; every daemon predating the field writes nothing |
Mid-roll honesty: a plugin image predating the field ignores the
stamp and renders the tile again, so an estate that rolls the daemon
before the Traefik image sees the embedded-iframe tile RETURN until the
image rolls. Cosmetic, bounded by the roll, and deliberately preferred
over the drop’s failure mode (a broken launcher on the unplaced host for
as long as the key is set, on every plugin version). The plugin’s
list filter is now real: serveLauncherApps drops placed: false
entries in the same visible loop as the tenant and envfilter
predicates, keeps them for menuTenantOf and injection, and both
directions are pinned in menu_inventory_test.go
(TestPlacedFalseDropsTheTileAndNothingElse,
TestAnUnplacedHostStillGetsTheLauncher).
18. The launcher shell: two shells, one bootstrap (ruled 2026-08-13)
Section titled “18. The launcher shell: two shells, one bootstrap (ruled 2026-08-13)”The approved two-shell architecture: the plugin’s injected bootstrap stays a small pinned constant (the byte-ceilinged payload of §12.8), and the fullscreen panel it opens is replaced by a CSR launcher shell, a real bundle, served same-origin by the plugin from a DAEMON-MATERIALISED file, so shell iterations ship with ce releases and never need a plugin image repin. The bootstrap keeps its built-in vanilla panel as the permanent fallback: the shell is an upgrade, never a dependency.
The endpoint-namespace widening (owner ruling 2026-08-13). The
plugin serves /.shc/launcher/shell/* (static, content-addressed
files only, no dynamic behaviour) as the fourth reserved prefix beside
§3’s three endpoints. Same-origin for the same reasons as everything
else in §2 (no CORS surface, no third-party fetch, no CSP concession
naming a foreign host).
The materialisation contract (ce 6ccb71d9,
ce/modules/app/launcher_shell.go). The daemon side of the same
doctrine that ships apps.json and the icons: the file is the
interface, the plugin’s only I/O is reads off the license mount.
Rendered by every build of the clusterfs licence section, atomic
(temp+rename), content-idempotent, ASSETS BEFORE MANIFEST so a build
can never hold a manifest naming a file that is not in it.
| manifest | <licence section>/launchershell/manifest.json: {"version":1,"js":"<name>","css":"<name>"}; css may be absent (inlined styles), js never is |
| version | 1; the plugin ignores any other value. Additive fields need no bump |
| assets | sibling files in the same directory, content-addressed: the name IS the sha256 of the bytes |
| name rule | `^[0-9a-f]{64}.(js |
| serving | Content-Type by extension table (two entries, closed set, never sniff); names are digests, so Cache-Control: immutable-class caching is sound; superseded assets stay on disk (the plugin re-reads the manifest on its own TTL, and deleting old names is the only way a roll can 404) |
| absent/unreadable manifest | NO SHELL; the bootstrap keeps its built-in panel. Never an error a user sees |
Where the bytes come from. ce/core/launchershell, an embedded
asset in the ce binary. ce alone ships a PLACEHOLDER (a tiny script
that logs and leaves the built-in panel in charge); the shc build
injects the real bundle via launchershell.SetBundle(fs.FS) with
shell.js (required) and shell.css (optional) at the FS root. The
hashed stored names are computed by the materialiser from the bytes, so
no hand-maintained hash exists anywhere. The real shell build is the
springboard-ui extraction lane’s deliverable; until it lands, every
estate materialises the placeholder and nothing changes visually.
19. The plugin’s shell half: serving, the loader, the fallback
Section titled “19. The plugin’s shell half: serving, the loader, the fallback”The plugin side of §18’s contract (traefik/plugin/shell.go, and
csr() in the payload). The bootstrap keeps the trigger, both OIDC
legs and the credential ladder exactly as they are; what changes is
what an OPEN renders. This is the two-shell shape: the byte-ceilinged
bootstrap is the outer shell that must land on anyone’s page under
anyone’s CSP; the CSR bundle is the inner shell that may grow like an
application, because it rides its own endpoint and never the injected
constant.
How the assets are served
Section titled “How the assets are served”GET /.shc/launcher/shell/<name>, reading
/shc/license/launchershell/<name>, and every clause is
load-bearing, the same discipline as the appicons contract (§12.8.1):
- The name is matched against §18’s rule (the plugin’s
shellValidStoredName, yaegi’s reimplementation ofapp.ValidLauncherShellName) before it is joined to the directory. - The bytes are re-hashed and must equal the name. The response is
cached
public, max-age=31536000, immutable(the name is the version), so a torn read of a mid-write file must become a 404 and a vanilla panel, never a browser’s forever copy of garbage. Content-Typefrom the extension by closed table (text/javascript/text/css), never sniffed;X-Content-Type-Options: nosniff; adefault-src 'none'CSP on the asset response itself.- No identity required. The assets are static, content-addressed
and carry no data; the names ride only the authenticated
/appsresponse, so an anonymous visitor learns nothing, not even a digest. - One refusal shape: 404, no body,
no-store, malformed name, missing file, oversized file and digest mismatch alike.
The manifest is read on the same TTL and last-good rules as
apps.json, and it is honoured whole or not at all: a malformed
name anywhere in it reads as “no shell” and the estate keeps the
vanilla panel.
Where the bootstrap learns the names
Section titled “Where the bootstrap learns the names”On the /apps response, as an additive shell field
(launcherShellRef, short keys j/c), not a manifest endpoint.
Same reasoning that put the glyph sheet there: the bootstrap needs the
names exactly once, at the moment it already holds an answered
inventory, and a fetch that already happens once per page view is
cheaper than a new unauthenticated JSON endpoint in the reserved
namespace plus a second round trip and its own failure mode. The
bootstrap being a compile-time constant is what rules out embedding the
hashes in the page: a per-estate byte in the payload would break the
constant-CSP-hash property everything else rests on.
The loader, and the fallback doctrine
Section titled “The loader, and the fallback doctrine”csr() in the payload runs on the first open only. A visitor who
never presses the trigger costs nothing. It fetches the CSS as text and
applies it through new CSSStyleSheet() + adoptedStyleSheets on the
shadow root (a <style> element would be an inline style for CSP
purposes; a constructed sheet needs no directive at all), then injects
<script src="/.shc/launcher/shell/<hash>.js"> non-parser and calls the
bundle’s window.SHCLauncherShell.mount(el, {apps, data, close}):
the mount point inside the same shadow root, the same-origin /apps
path, the inventory the page already holds, and the close function the
trigger and Escape share.
Every failure falls back to the vanilla panel, and none is dark:
no manifest on the mount, an engine without constructable stylesheets,
a CSS fetch that dies, a script that 404s or is refused, a script that
defines no mount() (ce’s placeholder, a stale cache), and a mount()
that throws. One attempt per document (a failed bundle is not
re-fetched on every press) and nothing tab-scoped is written (the
anti-latch rule stands). The guards drive the real payload through node
(launcher_shell_node_test.go): a placeholder shell through the full
path, and the panel through every fate above.
An external same-origin script is governed by the page’s script
directive, and a hash cannot admit a src= load. The cooperation path
grew a fourth editor (cspRelaxScriptSources): when, and only when,
the mount actually carries a shell, the injector claims
https://<host>/.shc/launcher/shell/, this origin, path-bounded to
the plugin’s own namespace, never a bare 'self'. The merge is
monotone (a host source never disables 'unsafe-inline' the way a hash
does), never touches a 'none', and appends nothing to a policy that
already admits the load: SonarQube’s measured policy carries 'self'
and comes out byte-identical, which is pinned by test. Policies with
'strict-dynamic' need no claim at all; the hashed bootstrap inserts
the shell script non-parser, which strict-dynamic trusts transitively.
The payload cost
Section titled “The payload cost”The loader added 1,350 bytes to the injected constant (10,318 →
11,668, over the always-label lane’s landing), all of it addition
because the fallback doctrine keeps every byte of the vanilla panel
shipping. Simplification came first (the first cut’s duplicated XHR
helper was folded into get() as a raw flag, −220), and the ceiling
was raised 10,350 → 11,700 with the arithmetic written over
menuPayloadByteCeiling, per the standing rule that a raise carries
its justification in the test.
What the shell-build lane owes
Section titled “What the shell-build lane owes”The bundle (separate lane; ce ships a placeholder until then) must:
- be a single classic-script
.js(plus optional.css) that defineswindow.SHCLauncherShell.mount(el, opts)and renders intoel; - read its data through
opts.apps(the same-origin inventory path) and treatopts.dataas the already-answered first load; - call
opts.close()to dismiss; the bootstrap owns the trigger, focus return and the Escape key; - carry no absolute origins; everything it fetches must be same-origin under the page it lands on;
- ship as
shell.js(+ optionalshell.css) injected through ce’slaunchershell.SetBundle(§18); the materialiser computes the content-addressed stored names, and the plugin refuses anything whose bytes do not hash to its name.
20. One tile per stack: sidecars, vapps, extra environments
Section titled “20. One tile per stack: sidecars, vapps, extra environments”Clay’s ruling of 2026-08-14, restating Q1: one icon per STACK. Extra deployments, vapps, and plugs that are not the primary UX belong in that tile’s right-click (or long-press) menu, never as their own tile.
Entitlement is still per deployment. dedupeMenuTiles still keys on
(tenant, environment, stack). The three Frappe benches (bit,
erpnext, ffx) stay three tiles because they are three stacks. What
changed is DISPLAY of the extras that used to sit beside them.
| Extra | How it reaches the menu |
|---|---|
| Extra environment of the same stack | dedupeMenuEnvironments keeps the precedence winner as the tile and appends the loser as k kind e |
| Sidecar stack (nextcloud-picker) | catalogue belongs_to: nextcloud; daemon stamps belongsto; plugin foldMenuStack (baked fallback covers an un-stamped live file) |
| Installed vapp instance | already stamped as vapps on the parent entry; copied onto k kind v (no href; no routed host) |
| Webhook / no UX (gitlab-huly) | launcher_placed: false, no parent, omitted, not folded |
Wire on the inventory tile: k: [{n, h, p, t}]. t is e (environment),
s (sidecar), or v (vapp). The vanilla overlay’s arm() opens that
list on contextmenu and on a 500ms long-press. A sidecar with no matching
parent tile stays a tile (picker without nextcloud). Two or more parent
tiles of the same catalogue app in one environment (the frappe benches)
leave a sidecar that named that app unfolded; folding onto bit
because it appeared first would hide it behind the wrong company’s books.
21. The launcher’s design law: the standing owner rulings
Section titled “21. The launcher’s design law: the standing owner rulings”The rulings that shape the overlay, in one place, so a session that touches the launcher can cite the rule it is following (or the one it is about to ask the owner to change). Each entry names the ruling, the date and the code that enforces it.
-
Literal iPad springboard. The overlay reads as an iPad Home Screen (wallpaper, squircle icon field, glass dock shelf), not as a file picker. (2026-08-14;
dress()inmenu_homescreen.go, guarded bymenu_homescreen_test.goand the fill/scroll node harness. The page dots that shipped with it are gone: §21.5’s Ruling 3 replaced the page strip they indexed with one vertical scroller.) -
One icon per stack. A stack is one tile; extra environments, sidecars and vapps ride that tile’s right-click / long-press menu (§20). (2026-08-14;
menu_stack.go.) -
X-only dismissal. The Applications overlay closes on its close control, on Escape (keyboard a11y, the keyboard user’s X) and on activating a tile. It NEVER closes on a press of its own background: the overlay is a workspace, not a transient popover, and on a phone the empty space between icons is most of the screen, so a backdrop dismiss made every missed tap close the workspace. (2026-08-16, reported from mobile Safari on the live corp estate; the removed handler was
if(e.target===pane||e.target===grid)shut()inmenu.go, andTestLauncherOverlayDismissesOnXOnlyrefuses its return.) -
No wiggle mode. “We don’t even need a wiggle mode.” There is no in-launcher edit mode of any kind: no long-press-to-edit, no jiggle animation, no drag-to-reorder, no drop-to-folder, no per-user layout persistence. Icon arrangement is whatever the served inventory says (
BuildAppsMenu’s order); changing it is a config change, not a gesture. (2026-08-16; the ruling removedmenu_arrange.go,launcher_layout.goand the PUT leg of/appswhole;TestLauncherHasNoWiggleMode(since narrowed and renamed; see the amendment below) refuses the chrome’s return. The mode’s reproduced defects are recorded below so nobody rebuilds it “fixed”: blank unmarked folder tiles, a blockingwindow.promptrename whose answer never reached the caption, a near-transparent folder board the springboard bled through, an outside-tap that closed the overlay and latched the stale board over the next open, and a 400ms/500ms long-press collision that fired edit mode and the §20 extras menu from one hold.)★ AMENDED 2026-08-16: the scope was read too wide
Section titled “★ AMENDED 2026-08-16: the scope was read too wide”The clause above is superseded in its scope and kept in its defect list. It banned folders, drag-to-reorder and drop-to-folder along with the jiggle; the owner’s correction, the same day and verbatim:
“When I say no wiggle mode, I still want the ability to have folders. They’re not incompatible. Right? Like, the no wiggle mode, it’s not even called no wiggle mode. It’s just where don’t do the wiggle. And you can press and drag into folders or press and drag around, or you can just click press it or click on it, and it opens. Or you can right click on it or long press on it, and it pops up the menu. But we shouldn’t need a wiggle mode to do any of that.”
What the ruling actually bans, and it is two things:
- the jiggle: no rotate interval, no
shc-jiggle, no animation of any kind on a resting tile; and - the mode: no entry point, no state to be in, no way out. There is no hold-to-enter-arrange, no edit flag, no “done” affordance.
What it does NOT ban: folders, drag-to-reorder, drop-to-folder, or a per-user arrangement that persists.
The target is DIRECT MANIPULATION with no mode at all. One
pointerdownon a tile resolves to exactly one of three outcomes, on two independent thresholds:gesture condition outcome tap / click release with travel ≤ 8px before 500ms the app opens, unchanged press and drag travel > 8px, at any time the tile moves: reorder, or drop dead-centre on another tile to make a folder long-press / right-click 500ms elapsed with travel ≤ 8px a context menu pops up (Open, or Rename on a folder, plus the §20 extras) They are mutually exclusive by construction, not by luck: movement past the slop CLEARS the pending hold timer, and a fired hold latches
CMsopointermovereturns early.TestFoldersHoldAndDragCannotBothHappenis the assertion that neither half can be deleted quietly.The recorded defect list above is unchanged and is now the acceptance criteria. Each is proven absent by a named test in
menu_folders_node_test.go, driven through the nodevm.Scriptstub DOM against the SERVED payload:defect how it is answered test blocking window.promptrename whose answer never reached the captioninline <input>above the open board; commits on blur and Enter, reverts on Escape, writescap.textContent, persistsTestFoldersRenameIsInlineAndReachesTheCaption,TestFoldersRenameEscapeRevertsblank unmarked folder tiles mini()paints up to four MEMBER pictures through the sameglyph()the tiles use, repainted on every membership changeTestFoldersDropOntoTileFormsAFolderAndOpensItnear-transparent folder board opaque #0d1426board over its own 72% scrimsame test outside-tap closed the overlay and latched the stale board the tap lands on the SCRIM and closes the BOARD only; shutF()REMOVES board, scrim and input and nulls every handle, andopenF()calls it firstTestFoldersCloseTearsDownAndNeverLatchesTheStaleBoardthe 400ms/500ms long-press collision there is now exactly ONE hold timer in the payload; menu_stack.gono longer installs its own touch long-press and only records the tile’s extrasTestFoldersHoldOpensTheContextMenuAlso built, from the owner’s description: forming a folder OPENS it immediately; tiles reorder inside an open folder with the live reflow preview (neighbours shift out of the way DURING the drag off a frozen grid, shift back if the finger returns, and commit only on release); the dragged tile is ghosted at 0.6 opacity with a slight scale; a dead-centre hover shows a distinct folder-forming ring (
shc-fd) against the between-tiles reorder state (shc-mv); a tile carried beyond the board’s bounds returns to the page; and a folder down to one member collapses back to a plain tile IN THE FOLDER’S OWN SLOT.A fourth defect, reported separately and fixed here: a long-press raised the browser’s native text selection over the tile. The panel sets
user-select,-webkit-user-select,-webkit-touch-calloutand-webkit-tap-highlight-color; the rename input setsuser-select: textback, because a field you cannot select in is a field you cannot rename in. (TestFoldersSelectionIsSuppressedOnThePanel.)What did NOT come back, and stays refused by
TestLauncherHasNoWiggleAndNoPrompt:shc-jiggle,W.setInterval(the jiggle’s engine),prompt(,'PUT'(the layout is localStorage-only, per host; re-adding a mutation to/.shc/launcher/means designing CSRF for the most widely exposed surface SHC has), andshc-home-(the retired per-user key prefix).TestLauncherHasNoEditModepins the other half: that the payload’s one hold timer opens a MENU and that the tile click is gated on the two gesture latches rather than swallowed unconditionally.The code is
menu_folders.go(home()), spliced at IIFE top level besidedress()andgrab(). Payload cost: 16,400 → 28,100 on the ceiling, measured 27,835, itemised onmenuPayloadByteCeiling. - the jiggle: no rotate interval, no
The long-press that REMAINS is §20’s extras menu, now folded into the launcher’s single context menu; the payload has exactly one hold timer and one popup, which is what retires the collision recorded above.
21.5 The gesture model: four rulings, one recogniser (2026-08-16)
Section titled “21.5 The gesture model: four rulings, one recogniser (2026-08-16)”Four rulings arrived together and they are one gesture model, not four tickets. The first is the root one and the other three are unsatisfiable without it.
Ruling 1: a drag arms on the LONG-PRESS, never on touchdown. “You
shouldn’t be able to drag an app until holding long enough for the menu
to open. That way normal scrolling scrolls the window.” Until this
lane every tile carried touch-action: none and was armed from
pointerdown, so a swipe that started on a tile dragged the tile
instead of scrolling the field. The hold that already raised the context
menu now also arms the drag (one timer, one recogniser, one source of
truth), and one pointerdown becomes exactly one of four things:
| outcome | condition | thresholds |
|---|---|---|
| TAP | release under slop before the hold fires | T = 8dp |
| SCROLL | travel > T before the hold fires | T = 8dp, HD = 500ms |
| MENU | HD elapses under slop | HD = 500ms |
| DRAG | travel > T after HD | T = 8dp |
The cancellation rules are what make it feel native, and each is guarded by name:
- movement past T with the timer pending cancels the press: the
timer is cleared, the stream released, and nothing is
preventDefault()ed, so the gesture belongs to the scroller (TestFoldersSwipeOnATileScrollsAndDoesNotDragIt); - that cancelled press also does not launch the app on release (iOS and Android both cancel the activation at the same slop) and the swallow is one-shot, so the next tap opens it;
- a completed press suppresses the click its release would fire
(
CM), and stays armed until release even if the finger rests (TestFoldersHoldThenStillDragsAfterAPause).
touch-action alone is advisory once a gesture has begun (a browser
fixes the effective value at touchstart), so a non-passive
touchmove listener on the panel takes the gesture back while armed,
and does nothing at all otherwise.
A mouse arms immediately. A mouse drag cannot scroll anything, so
there is no scroll to protect and a hold would only cost the desktop
pointer drag a prior lane fixed. One documented exemption
(e.pointerType === 'mouse'), not a second model
(TestFoldersMouseDragNeedsNoHold).
Ruling 2: a drag closes what is open over it. “When I long press
and the stack menu opens, when I drag another icon the stack menu should
disappear.” The stack menu is dismissed by a document-capture click and
a drag fires no click, so it used to hang over the field pointing at a
tile that had moved; m.hide (its own teardown, listener included) is
now called the instant a drag begins. The folder board closes with it,
except for a drag that STARTED inside the board, which is drag-out
and must not have its container deleted mid-flight. And because the
board’s scrim covers the pane at z-index 7, a press aimed behind it
never reaches a tile at all: the scrim now closes the board on
pointerdown as well as on click, which is what makes the ruling true
for a finger rather than only for a synthetic click.
Ruling 3: overflow scrolls DOWN; the page strip is retired. “What
happens when there are more apps than the window holds? I guess they
just vertically scroll down because screen sizes are dynamic.” What
this replaced was deliberate: .shc-pages, scroll-snap and a page-dot
row, i.e. a faithful iPad springboard. The argument for changing it is
the owner’s own and it is a correctness one: a page has a capacity,
and capacity is measured from a viewport that moves. cols×rows is
recomputed on every resize, the stored layout is per page (L.p[]), so
every rotation re-cut the boundaries and split what the user arranged.
One scroller has no boundary to move.
The row UNIT is load-bearing and was caught only in a real browser: with
repeat(rows,1fr) an overflowing field simply compresses its rows to fit
(measured at 390×844: rows 91.9/67.0×5/95, scrollHeight 642 =
clientHeight 642; overflow-y: auto with nothing to scroll). The
overflowing field re-declares the same tracks in PIXELS.
Ruling 4: the favourites bar scrolls sideways. “If the favorites
bar can’t fit everything it should horizontally scroll.” overflow-x: auto, flex-wrap: nowrap, a fixed 60px icon (never shrunk below the
touch target) and (the part that took two attempts) justify-content: safe center rather than a measured flip: plain center on an
overflowing row put the second of nine entries at x = −39, off the
scrollable origin, and a measured version could not see the dock at all
because lay() runs before apply() restores it. dropAt()’s
four-item cap and its eviction branch are gone with it: the bar never
silently drops an entry.
The two axes are kept apart by the browser, not by a JS guess. The
field declares touch-action: pan-y, the bar pan-x. Neither is a
scroll container for the other, so there is no chaining to arbitrate and
a diagonal swipe at the boundary cannot drive both.
Proven in a real Chrome at 390×844 with real touch input (32 stubbed
apps, 28 on the field): a swipe starting on a tile moved the field
0 → 143px with the order unchanged and no tile translated; a 750ms hold
raised ["Open"]; the following drag ghosted the held tile, translated
two neighbours and closed the menu; the drop reordered; a dead-centre
drop formed and opened a folder; a press on the scrim closed the board
on pointerdown; a drag out of an open folder kept the board up and
collapsed it on release; and a horizontal swipe on a nine-entry bar
moved scrollLeft 0 → 232 while scrollTop stayed 0.
Payload cost: −185 bytes (31,180 → 30,995 measured on the rebased tree; the ceiling stays 31,500). Ruling 3 deleted more than Rulings 1, 2 and 4 added, because the gesture work reuses the hold timer that was already there.
22. Surviving the app: mounting, removal, and the retry ladder
Section titled “22. Surviving the app: mounting, removal, and the retry ladder”Measured on bitspur 2026-08-16 with a real browser holding a real corp
session, across all 33 routed hosts in apps.json. Two failures were
found, and neither one is an identity failure, a routing failure, a
CSP failure or a gating failure. Both are “the marker is in the served
HTML, the payload ran, and the user sees nothing”, which is the shape
§7’s ladder was built to end, and did not.
22.1 The app owns the DOM, and the payload assumed it did not
Section titled “22.1 The app owns the DOM, and the payload assumed it did not”siem.corp.bitspur.com (Wazuh) ran the payload to completion (both
/.shc/launcher/apps calls, 401 then 200, are in the router’s own access
log), and when the page settled neither the injected
<script id="shc-apps-menu"> nor <div id="shc-apps-launcher"> was in
the document. A MutationObserver armed at document start on
documentElement with subtree: true recorded no removal, which is
the tell: the nodes were never removed from the live tree, they went away
with the body they were in. Wazuh replaces document.body.
The payload used to capture the body ONCE, at IIFE time:
var B=d.body||d.documentElement;so after the swap B is a detached node, and B.appendChild(root) mounts
the launcher into a tree that is no longer in the document. Present in
memory, correct in every other respect, invisible on screen, silent in the
console, and indistinguishable from every other “menu absent” report.
Two changes, both in menuBootstrapScript:
B()is a function, read at use time. A body swap can no longer strand the mount.keep(root)arms achildList,subtree:falseMutationObserver on exactly two nodes (<html>(fires only when<body>itself is swapped) and the body the root currently lives in (fires only on its DIRECT children)), debounced onto one zero-delay timeout. A framework patching inside its own mount point, which is what a render is, fires neither. On a fire the whole test isd.contains(root).
It gives up rather than fight. menuReattachCap (20) bounds the
restorations. An app that removes the root in a loop and a payload that
re-appends it in a loop is a flicker and a busy loop on a page this repo
does not own, strictly worse than the absent launcher it is fixing.
TestLauncherStopsReattachingRatherThanFightTheApp asserts the giving-up
half; TestLauncherSurvivesAClientSideRerender asserts the other.
22.2 un was an outage treated as a verdict
Section titled “22.2 un was an outage treated as a verdict”probe’s un bit is /start answering 503 identity-check-unavailable,
which serveLauncherStart returns for exactly one reason: the daemon
could not be reached for realm-for-host inside gateAuthzTimeout. It is
a statement about the ESTATE at one instant, never about the caller.
The payload answered it by rendering neither the menu nor the sign-in offer, and never asking again for the life of the document (§6’s “two cases render nothing”). So one slow daemon call cost the user a launcher until they happened to reload, and there was nothing in the page, the console or the network panel that said so.
From bitspur’s retained access log on 2026-08-16: 24 of ~70
/.shc/launcher/start requests answered 503, spread over ten hosts
including grc, design and fleet.
The boot flow is now a bounded ladder (2s, 8s, 30s) down the un
branch only. Every other outcome keeps its existing behaviour, because
every other outcome is DECIDED rather than transient:
| outcome | behaviour | why not retried |
|---|---|---|
| inventory answered | build | flow() is guarded by getElementById and never re-enters |
| proven, no tiles | nothing | an empty launcher is worse than none; re-asking cannot change it |
not proven, not un | the sign-in offer | the offer IS the affordance; a timer behind it is a request nobody asked for |
un | retry, ×3 | the daemon was down, and daemons come back |
A healthy estate pays nothing: the retries exist only on a page that
already failed. TestLauncherRetriesWhenTheProxySaysTheCheckIsUnavailable
and TestLauncherDoesNotRetryADecidedAnswer are the two halves.
22.3 What the class sweep actually found
Section titled “22.3 What the class sweep actually found”33 routed hosts, one browser, one corp session, settled page:
- launcher rendered: knowledge, grc, sbom, sbom-api, fleet, git, glitchtip, projects, llm, mail, matrix, matrix-auth, meet, mautic, design, artifacts, workflows, cloud, chat, quality, marketplace, api.marketplace, hq.flyingfoxlabs.
- injected, ran, invisible:
siem, §22.1, now fixed. - sign-in offer rather than the menu:
marketplace,api.marketplace,hq.flyingfoxlabs, expected, §8’s mixed registrable domains. - never injected:
hq,erp(Frappe, §8’s SSO-selector route, known and unfixed),gitlab-huly(launcher_placed: false, correct),errors,license.selfhostedcloud.org,picker, and the gatedidm/agents/openreplay. Coverage of those belongs to the flagship-coverage lane, not here.
23. The profile, settings and the console
Section titled “23. The profile, settings and the console”Owner, 2026-08-16: “Also I need a profile icon and link to go to settings and one to go to console.” He asked twice before, in different shapes: “shouldn’t there be, like, a user profile that when pressed goes to the console” and “isn’t there supposed to be an app called settings and an app called marketplace”.
Source: traefik/plugin/menu_profile.go, whose header carries the whole
argument; this section is the estate-facing summary.
AMENDED 2026-08-18: the sheet is gone. The owner withdrew the dropdown: “i don’t want this dropdown menu on the floating menu. instead clicking the icon should take me straight to the console.” The chip is now an anchor whose href is the console, and Account and the refusal rows are deleted rather than hidden. Everything below about the SHAPE (chrome, not a tile) and the SOURCE of the identity still stands; the parts about the sheet’s rows are history. §27.5 has the amendment and the edge cases.
AMENDED AGAIN 2026-08-21: the door is the account profile. The avatar opens
<issuer>/account/on the launcher and in the Console alike, and the URL is the CALLER’s realm, published by the daemon on/api/user/effective-apps. §27.5.1 has it.
23.1 The shape, and why it is not three tiles
Section titled “23.1 The shape, and why it is not three tiles”Ruled here: the profile is FIXED CHROME in the panel header. Settings and Console are entries in the sheet it opens. None of the three is a tile.
The middle phrasing above asks for tiles, so the shape had to be decided rather than guessed. Two reasons decided it, and the second is the one that would have shipped a defect:
- A tile can be buried. As of §21.4 every tile is draggable from the moment it is built and a tile dropped on another becomes a folder. That is the feature. It also means anything in the field can be put inside a folder called anything, and this launcher has no app drawer, no search and no reset-layout verb, so the grid is the only index there is. For an ordinary app that is intended. For “who am I signed in as” it is not: an identity affordance the user can lose is one that cannot be trusted to be checked. Every system that ships one puts it in fixed chrome, and none of them makes it a home-screen icon.
- A tile must open something, and neither of these opens anything
today. Measured 2026-08-16 on this tree: there is no
settingsapp in the catalogue: 103 app directories underapps/, not one named settings;deploy/shc/holds exactlymarketplaceandportal. And nothing serves the console on any estate: no daemon serving route, nodeploy/stack, no catalog entry;apps/consoleis a build workspace CI typechecks (MR !45 measured the same from the licensing side and TIERS.md records it). Asettingstile and aconsoletile would both point at nothing. (Update 2026-08-20: the console half expired the same day;8bc18cc8clanded the serving route, traefik route and launcher entry, which is this section’s “door” swinging open exactly as the next paragraph describes. Thesettingshalf of the measurement still stands.)
marketplace, which the owner named in the same breath as settings, is
the contrast that makes the finding legible: it is a routed stack
with a host, which is why it already has a tile and vendored art. The
launcher tiles what the estate ROUTES.
The door is left open both ways, and it needs no switch. The moment
an estate routes a console or a settings stack, apps.json names it
and the launcher tiles it automatically: first-class, draggable,
foldable, like any app, with no code change. The profile row does not
become redundant then; it becomes the unburiable route to the same
place. That is the honest reading of “both”: tiles for what the estate
routes, header chrome for what must always be findable.
TestProfileChipIsHeaderChromeNotATile holds the position in the DOM
three independent ways (parent is the header; no ancestor is the field;
the drag machinery has not armed it). TestNoSettingsAppExistsInTheCatalogue
holds the measurement, and fails the day somebody creates a settings
app, a prompt to re-read this section, not a regression.
23.2 Where the identity comes from: nothing new
Section titled “23.2 Where the identity comes from: nothing new”/api/user/effective-apps answers {"version":1,"user":"…","apps":[…]}
and menuClient.fetch had been decoding that user and throwing it
away since the endpoint was adopted (§7). It is now carried through the
verdict cache onto the response. No extra daemon call, no new
endpoint, no header, no cookie.
That choice is load-bearing rather than tidy. The plugin’s other
identity (menuIdentity.User off the forward-auth proof) is empty
for most real users: the entitled-elsewhere rung reaches the inventory
precisely because forward-auth refused them, and it used to construct
&menuIdentity{Tenant: tenant} with no user at all. On bitspur that is
42 of 43 realm users. A profile built on the proof header would have
been blank for almost everybody while every idAdmits test stayed
green, this subsystem’s signature defect.
TestProfileNamesTheUserOnTheRungThatServesRealPeople is written
against idRefuses for exactly that reason.
The name rides the private inventory response (me.u), never the
injected payload, which stays a caller-independent compile-time
constant. TestTheProfileBlockIsNotInTheInjectedBytes names it.
23.3 Settings = the realm’s account console
Section titled “23.3 Settings = the realm’s account console”There is no settings app to link to, and the console’s own settings
screen (apps/console/routes/settings.tsx) is inside the console and
therefore behind the Hobby gate; pointing Settings there would put the
one surface every user needs behind the one gate that was just added.
So Settings is the Keycloak account console of the realm that gates
this host: {issuer}/account/. It is real, deployed, per-user, on
every estate this product has stood up, ungated at every tier, and it is
the settings of the identity the chip above it names. The issuer comes
from the same realm-for-host lookup the silent check already makes
(§6), cached per host for 30s, misses included; 24 of ~70 realm
lookups answered 503 in one bitspur window (§22.2) and an uncached miss
would re-ask on every page view.
An unresolvable realm means no Settings row. This plugin has refused to guess an issuer since §7 was written; a settings link into a hostname nobody verified is that same defect with a friendlier face.
23.4 The console’s tier constraint: asked, never re-derived
Section titled “23.4 The console’s tier constraint: asked, never re-derived”Owner ruling 2026-08-16: “No console requires at least hobby.” MR !45
landed it as the console feature key behind one daemon door,
shc.console.gate (modules/console/gate.go).
The launcher asks that door, with the caller’s own credential, the
same credential the verdict call already carries to the same daemon on
the same request. It derives nothing itself, and could not: license.go
in this plugin reads posture (keyed / trial / degraded) and knows
nothing about tiers, so a local decision would be a guess wearing a
gate’s clothes. The daemon’s own header says why a client must not
answer this: a client-side GateRefuse resolves StateUninitialized,
which is permissive by no-brick doctrine, and would wave everyone
through.
| gate answers | the row is |
|---|---|
| 200 | a live link, if this tenant also routes a console the caller may open |
| 200, nothing routed | the sentence “not deployed on this estate” (the state every estate is in today) |
403 X403029LICENT | a refusal naming Hobby, with the shc license status pointer |
403 X403036LICOPT | never licensed, so the trial pointer, not a renewal |
| 403, any other code | no row; an authz 403 is not a licensing claim |
| 404 / 5xx / unreachable | no row; a community daemon does not carry the route (absence doctrine), and a daemon that did not answer has told us nothing |
The last two rows are the point. Painting “requires Hobby” off a transport failure would be a licensing claim invented by a proxy, and the estate reading it could not tell it from the truth.
The refusal is never an anchor. The row is an <a> when there is
somewhere to go and a <div> when there is only something to say:
TestProfileConsoleRefusalIsNotAnAnchor drives the payload and fails if
one href= appears in the wrong branch. That is the runtime no-brick
contract at the last place it can still be broken.
Both questions must pass. The estate’s entitlement is the gate’s; the caller’s permission is the RBAC verdict’s. The console link is built from the tiles the caller is already being shown, so a console the caller holds no role on is not linked even on an entitled estate.
What this deliberately does NOT do: filter TILES by entitlement. If
an estate routes a console stack, that host keeps its ordinary tile
whatever the licence says. Three reasons, and they are the same reason
three times: the tile comes from apps.json, which is the daemon’s
routing record and says the host serves something; the console’s own
bootstrap consults the same shc.console.gate and shows its own refusal
on its own surface, which is where a product’s paywall belongs; and a
launcher that filtered tiles by entitlement would be making a licensing
decision per app, which is a far larger claim than this subsystem is
entitled to make. The profile row is the launcher’s own affordance and
is the one thing here that must not lie about the tier.
23.5 The copy lives on the wire, not in the payload
Section titled “23.5 The copy lives on the wire, not in the payload”Every sentence a user reads about the tier is built server-side onto
the private inventory response (launcherProfile.ConsoleNote). That
response is no-store, same-origin and fetched once per page view; it has
no byte ceiling. The payload’s entire share of the tier constraint is
p.c ? link : p.cn: two branches, no strings.
Had the copy ridden the payload it would have cost every anonymous
visitor on every host of every estate several hundred bytes to carry a
sentence none of them can read. TestTheProfileCarriesNoCopyInThePayload
refuses it, and refuses being satisfied by deleting the feature.
23.6 The ceiling
Section titled “23.6 The ceiling”menuPayloadByteCeiling 29,000 → 31,500, measured 31,041 served
bytes (28,651 + 2,390). The 2,390 is one payload function, who(): the
header chip, the sheet it creates and removes, and the two rows. The
constant’s own comment carries the decision, as §14’s raise required of
every raise after it.
24. The press must survive the sign-in (ruled 2026-08-16)
Section titled “24. The press must survive the sign-in (ruled 2026-08-16)”Owner: “when I press the floating menu and I’m logged out it redirects me to login which is correct but then when it redirects back it doesn’t open the menu for me so I have to press it again.”
The sign-in worked. The intent was lost. The signed state carried
u (the callback URL), r (the realm), i (issued-at) and t (the
return path), nothing that said what the user was asking for. So the
callback could bring the user back to their page but not back to the
thing they pressed: the page reloaded, /apps now answered, and the menu
rendered shut beside a user who had already asked for it open.
Where the flag lives
Section titled “Where the flag lives”In the signed state, as o, and nowhere else. The callback honours
only what /start provably minted (that is why t rides there), and an
unsigned query parameter would let any link on the internet make
somebody’s launcher pop open. It is only a UI hint; it is still not
allowed to be the one unsigned input on a path built to trust nothing
unsigned.
The two entry paths behave differently, and that is the fix
Section titled “The two entry paths behave differently, and that is the fix”/start already knows which leg it is on:
| Leg | Query | May carry intent |
|---|---|---|
| top-level click-through | ?open=1&return=<path> | yes; a human pressed |
| framed silent check | (none), or ?silent=1 | no, ever |
The silent check runs unbidden on every page view of every injected
host. A dialog springing open off one would be a worse defect than the
one being fixed, so /start drops open=1 on that leg even when it is
written straight onto the URL: wantOpen := interactive && …. The flag
means “a human pressed”, never “this leg is top-level”; the two
coincide today only because the press is the sole thing that navigates.
One-shot, and the URL is never touched
Section titled “One-shot, and the URL is never touched”The callback answers a proven press by setting shc_launcher_open=1
beside the 302 home. The payload reads it and deletes it in the same
breath, at document scope, before anything asynchronous runs.
- the address bar, history entry and Referer are exactly what the user left; nothing is appended and nothing has to be scrubbed;
- a reload finds nothing;
- a back-button navigation finds nothing;
- a second tab on the same host finds nothing;
- the intent is spent even if no menu renders; an intent nobody could honour must not queue up for later.
A failed round trip (login cancelled, no code, a state that did not verify) mints nothing: there is no menu to open, and the sign-in offer is what should render.
This is not the tab-scoped latch §22’s anti-bounce rules forbid. That ban is on the payload minting a suppression latch for itself. This is a server-issued token of an intent the server watched complete, valid for one document, destroyed on read; the only thing the payload writes is the deletion.
Driven end to end in node against the served bytes
(launcher_intent_node_test.go): one cookie jar, three page loads: open
on the first, closed on the second and third, and an ordinary press still
opening the menu on the reloaded page.
25. One layout, per user, on every host (ruled 2026-08-16)
Section titled “25. One layout, per user, on every host (ruled 2026-08-16)”As of FZ-8531, the app-host /layout write route is retired. /apps
returns the stored revision and arrangement, but no write token: the
compact lay.t field (formerly launcherLayoutState.Tok) is absent.
POST /.shc/launcher/layout answers 405 without contacting the daemon,
even with a token obtained before the upgrade. GET and HEAD answer
404. This applies to both panel modes and every app host.
The read-only springboard panel (§30) still reads the user’s arrangement.
Arrange in the full console. The legacy grid fallback keeps changes in
this origin’s localStorage only and cannot seed or write the daemon’s
layout. Where the daemon holds a stored arrangement, every load merges it
over the local copy and the stored order wins, so a reorder made in the
grid comes back in the stored order after a reload. The dock is the
exception: this origin’s shc-dock wins, and the stored dock only seeds a
host that has none. The daemon’s self-scoped layout API and stored data
remain unchanged.
Sections 25.1–25.9 below record the retired app-host write design. Its same-origin token was readable by any app-page script, so its CSRF ladder could not prevent an app XSS from rewriting the user’s layout. Removing the route, token minting and write relay closes that authority entirely.
“I made a folder with windmill and sonarqube in it and put my tiles in the order I want on cloud.corp. Open the launcher from fleet.corp or idm.corp and it’s gone: back to alphabetical, no folder. I want ONE layout that follows ME.”
25.1 The diagnosis, measured before anything was designed
Section titled “25.1 The diagnosis, measured before anything was designed”The arrangement lived in localStorage under two flat keys. Measured on
the live estate 2026-08-16 by fetching the served page off
fleet.corp.bitspur.com and grepping the injected payload:
var T=8*K,HD=500,bd=null,sc=null,nm=null,cur=null,OF=[],KEY='shc-lay';var MV=0,DX=1,DY=2,KEY='shc-dock',s=btn.style,G=P(16),H=P(26);localStorage is per origin by specification. Every deployment
answers on its own hostname, so every deployment holds its own private
copy and no mechanism exists by which one could read another’s. The
folder is not lost or racing. It is in cloud.corp.bitspur.com’s
storage area and is structurally unreachable from anywhere else. It is
not a cookie, so the diagnosis is not the milder “wrong cookie scope”
one; there is no scope to widen, and the layout had to leave the browser
or the defect could not be fixed at all.
25.2 The identity question, and why it is already answered
Section titled “25.2 The identity question, and why it is already answered”The obvious fear is that on access: open hosts (17 of the 39 entries
in bitspur’s apps.json) forward-auth is not in the request path, so
the launcher would have no server-verified identity there and layout
sync would only work on gated hosts.
That fear is obsolete. The launcher stopped depending on the gate
when it grew its own silent OIDC check (§7): a framed prompt=none
authorize, exchanged server-side by the confidential client, leaving the
browser an opaque HttpOnly handle. /apps reads that handle, presents
the token to the daemon, and the daemon answers with the caller’s own
name. That name is already carried into menuIdentity.User and already
rendered into the profile block (§23).
The invariant that falls out of it is the clean part:
Layout sync is exactly as available as the launcher itself.
There is no state in which the launcher renders tiles but cannot name
the caller; /apps answers 401 with no body to anybody the daemon has
not named. So “which hosts get layout sync” is not a new question; it is
“which hosts get a launcher”, already asked and already answered.
A shared parent-domain cookie was not taken, for the two reasons §7
already refused design (A): it mints an ambient credential readable on
hosts SHC does not control, and it structurally cannot reach
hq.flyingfoxlabs.in, which bitspur routes and which is not under
.corp.bitspur.com.
25.3 What moved, and what deliberately did not
Section titled “25.3 What moved, and what deliberately did not”| Key | Where it lives now | Why |
|---|---|---|
shc-dock | localStorage, per host, unchanged | The reason to move the trigger is that this app’s toolbar is underneath it. §14’s argument survives intact. |
shc-lay | The daemon, keyed by the user, served to every host, and still written to localStorage as the offline copy and the fail-soft floor | A folder named “Ops” is a statement about how this person groups the estate. It is the same statement on every host. |
The old design note said the arrangement was “localStorage-only, per host, NO PUT”. That note conflated the two, and the split above is the correction.
25.4 The CSRF ladder: the objection the old design was refused on
Section titled “25.4 The CSRF ladder: the objection the old design was refused on”The old refusal was right that accepting a mutation under
/.shc/launcher/ means designing CSRF for the most widely exposed
surface SHC has. What it did not weigh is that the read endpoint beside
it is already unreadable cross-origin (/apps sets no
Access-Control-Allow-Origin, ever), which is what makes a
double-submit token actually secret here.
Four rungs, all required, one byte-identical 401 with no body:
- Origin. Present, and its authority equal to this request’s host.
Absent is a refusal, not a pass. The scheme is not compared:
gateRequestProtodefaults tohttpsbecause Traefik terminates in front, so comparing it would refuse every save on a plain-HTTP router, and an attacker who can answer for this exact host is already past this rung’s reach. Content-Type: application/json. Not a CORS-simple type, so no form, image or iframe can produce it, and a fetch that tries is held for a preflight this endpoint answers with nothing.- The token. HMAC over the credential fingerprint and the host,
minted on
/apps, echoed inX-SHC-Layout. No server-side store, it dies with the session, and one host’s token does not verify on another. - The credential. The same ladder
/appsclimbs.
What rung 3 does not claim. A script running in the page can read
the token, because the payload can. That is not closable (a script with
that reach can simply drive the launcher’s UI) and the honest bound is
that an XSS on somebody’s app buys the ability to rearrange that user’s
own tiles. Not read another user’s, not write another user’s, not learn
anything about the estate /apps did not already say.
25.5 Whose layout, and what happens on a conflict
Section titled “25.5 Whose layout, and what happens on a conflict”Whose: their own, and the route cannot express anything else. There
is no ?user=, no body field naming a subject and no admin override;
the storage key is the authenticated Keycloak sub and nothing the
caller can influence. That is stronger than an RBAC check, which is a
branch that a later edit can invert. The key is the sub rather than
the username so that renaming a user in Keycloak does not orphan their
arrangement.
Conflict: a compare-and-set on a monotonic rev, never
last-write-wins. A write states the rev it was derived from; a mismatch
answers 409 with the current layout in the body, so the loser
merges in one round trip instead of re-reading and guessing. There is no
force flag.
The retry is exactly one. Two devices both saving in a loop must not become a write storm.
The losing device does not re-render. A save is what a drag ends
in, so re-applying a merged layout mid-gesture would yank tiles out from
under a finger, a worse defect than a layout that catches up on the
next open, which it does, because the next open reads the merged copy
off /apps.
25.6 The import: his existing folder is not thrown away
Section titled “25.6 The import: his existing folder is not thrown away”rev: 0 is the seed write, admitted only when this subject has
nothing stored. The first origin whose launcher opens uploads whatever
that origin held. Later origins are refused with 409 and merge:
- The server copy is authoritative for order.
- A folder beats loose placement. A folder the local copy has and the server copy does not is created, and its members are removed from wherever the server had them lying loose.
- Anything else the local copy names and the server does not is appended, in local order, to the last page.
- Nothing is ever deleted by a merge.
Rule 2 is the one that matters and the reason the merge is ~1,000 bytes rather than ~200. A plain append-only union loses the owner’s folder whenever the origin without the folder syncs first: it finds both members already present, adds nothing, and “Ops” is silently gone. A folder is a deliberate act; a loose tile in the default order is the absence of one, and a deliberate act outranks an absence whichever host happens to sync first.
So the outcome is stateable in one sentence:
Membership and foldering are independent of which origin syncs first; only the position of items neither copy foldered follows first-seen order.
25.7 Failing soft, and never silently
Section titled “25.7 Failing soft, and never silently”| Situation | What happens |
|---|---|
| Daemon has no layout route (every estate, until this rolls) | /apps carries no lay at all. The payload leaves this origin’s localStorage alone, writes nothing, and renders exactly as it does today. |
| Store unreachable | Same as above. /apps still answers; the launcher still draws. |
lay present, rev 0, no arrangement | Asked, nothing stored → seed. |
| Write fails | localStorage was written first and unconditionally, so the arrangement is not lost. The panel is stamped data-shc-saved="0" and carries “Layout not saved: this device only”. |
Absent and empty must never be confused. If “could not ask” were
read as “nothing stored”, an outage would have every origin seed its own
copy and the last to load would win, the accidental last-write-wins the
whole design exists to avoid. Both halves of the plugin and the daemon
enforce the distinction, and the daemon answers X503931USRLAY rather
than an empty layout for exactly this reason.
25.8 The payload budget
Section titled “25.8 The payload budget”| Tree | Served bytes |
|---|---|
| Before this lane (fixture) | 30,995 |
Before this lane (live, fleet.corp.bitspur.com) | 30,992 |
| After this lane (fixture) | 33,393 |
menuPayloadByteCeiling 31,500 → 33,500.
Not one byte of the growth is layout data. The stored arrangement
rides the /apps response, which is same-origin, private, no-store
and read by nobody but the payload; the glyph sheet and the vendored
art already ride there for the same reason. The answer to “fetch it
separately rather than raise the ceiling” is that the data already is
fetched separately and always was.
What grew is the code: the merge (~1,050), the write with its
409-merge-retry-once and the not-silent failure stamp (~640), the
read/seed/import block (~330), and the plumbing (~380). It could have
moved out too (shell.go serves JS from
/.shc/launcher/shell/<hash>.js) and that was refused on a regression
rather than on effort: the injected payload is covered by a CSP hash
(§8), a <script src> is not, and moving it out means claiming a
script-src on every CSP-strict app on the estate, which is the exact
class of app the inline-hash path exists to serve.
25.9 Storage
Section titled “25.9 Storage”The daemon stores one row per subject in the existing generic kv
table (namespace launcher.layout, key sub:<keycloak subject>), so
there is no migration, no Ent schema and no codegen pass. The value is
opaque to the daemon: it does not parse the arrangement, validate
that a named tile exists or reorder anything, because the browser half
already treats the inventory as authoritative about which apps exist
and the layout as authoritative only about where they sit. What the
daemon does enforce is a 16 KiB cap, because an unbounded blob on a
self-scoping write route is a storage-exhaustion primitive for any
account.
26. The free and lapsed launcher: subscribe, and the banner that outlives it (ruled 2026-08-16)
Section titled “26. The free and lapsed launcher: subscribe, and the banner that outlives it (ruled 2026-08-16)”Owner ruling, verbatim:
“on free shc show the floating menu and when pressed route users through a subscription. Same thing happens when license expires although when license expires it also shows a banner on the website because floating menu is allowed to be disabled it’s just enabled by default.”
Four clauses, and the fourth is the subtle one.
26.1 What free did before this section existed: measured, not assumed
Section titled “26.1 What free did before this section existed: measured, not assumed”The launcher was free, and it was free by absence rather than by
decision: menu.go and launcher.go contained no licence check of any
kind, rc.Status was read by neither, and TIERS.md named the launcher
in no tier. The only tier question the launcher had ever asked was the
profile row’s shc.console.gate (§23.4), which decides one menu row.
So this is a carve-out from free, the second one this product has taken, and it is a larger one than the console’s: the console’s affected population was measured at zero estates, and the launcher’s is every estate that has one.
26.2 The gate: asked, never re-derived, and it is a POSTURE gate
Section titled “26.2 The gate: asked, never re-derived, and it is a POSTURE gate”shc.launcher.gate (modules/launcher/gate.go), asked by
menu_subscribe.go with the caller’s own credential on the same request
that already carries a credential to the same daemon.
| answer | launcher |
|---|---|
| 200 | the grid, today’s behaviour, unchanged |
403 X403036LICOPT | the subscribe pane in the trial voice |
403 X403029LICENT | the subscribe pane in the renewal voice |
| 404, 5xx, a non-licensing 403, a timeout | the grid |
The last row is what makes the roll safe. On the day this ships not one
daemon in the fleet carries the route; if 404 read as a refusal, every
estate on earth, paid ones included, would swap its grid for a
subscribe pitch until its daemon rolled. TestAnUnrolledDaemonRendersThe
GridExactlyAsBefore stands between the feature and that outage.
★ The daemon side is a POSTURE gate, not an entitlement key, and that
is a finding rather than a shortcut. Entitlements.Bool returns false
for an absent key, and Resolver.Allowed reads the held licence’s
entitlement map in StateKeyed. Coining launcher as a seventeenth
feature key would therefore have refused every licence already minted,
every paying estate, on day one, until re-minted and re-activated.
That is the rug TIERS.md and modules/license/doc.go promise cannot
happen. What the ruling actually distinguishes is posture: free is
StateUnlicensed, lapsed is StateDegraded, and paid is everything
else, which is exactly “Hobby and above” because no keyed tier sits below
Hobby. TestLauncherGateNamesNoEntitlementKey scans the source and fails
if that is ever “tidied” into a license.Allowed call.
26.3 What a refused caller is answered: the pane, and no inventory
Section titled “26.3 What a refused caller is answered: the pane, and no inventory”serveLauncherApps answers 200 with four keys and nothing else:
version, state: "subscribe", apps: [], sub. No tiles, no glyphs,
no vendored art, no shell reference, no profile. A free estate’s page
therefore learns strictly less than it did before this gate existed.
200 rather than 402/403 deliberately: the payload treats every non-200 as “render nothing”, which is right for a refusal it must not paint, and this refusal is the thing to paint.
The gate is asked after the identity ladder, so an anonymous or cross-tenant caller still gets the same silent 401. A subscribe pitch painted for a stranger would be an unauthenticated advert on somebody’s login page, and it would tell the world the estate is unlicensed.
26.4 Where “subscribe” goes: and the honest answer is “not all the way”
Section titled “26.4 Where “subscribe” goes: and the honest answer is “not all the way””Measured 2026-08-16 by dialling them: the apex and the marketplace answer
200; selfhostedcloud.org/pricing 404s; my.selfhostedcloud.org (the
customer portal, the ruled commercial surface) refuses the connection.
There is no checkout anywhere.
The estate cannot host one either, and that is a ruling rather than a
gap:
2026-08-16-marketplace-identity-and-install.md
rules one central store with purchases owned by central accounts, and
2026-08-16-portal-cluster-identity.md
rules that the portal federates into a cluster and never the reverse.
So the pane is a pointer, not a checkout, and it points at the two
things that exist: the CLI verb (shc license trial start /
shc license status), rendered as monospaced text because it is
something to type; and one configurable link (appsMenu.subscribeUrl,
default the live apex, off for none). What is missing, plainly: there
is no self-serve subscribe flow, no plan picker and no checkout. A click
lands a human on the vendor’s site.
26.5 The off switch, and its scope
Section titled “26.5 The off switch, and its scope”launcher_enabled, a top-level field of apps.json, absent meaning
on, the ruling’s “enabled by default”.
Estate-wide rather than per-deployment, decided rather than defaulted.
Per-deployment is already expressible and already spoken for:
appsMenu.enabled is ce’s internal plumbing (§8, the SSO-selector
middleware turns this injector off on login-page routers and back on for
the launcher router), so overloading it would make one switch mean two
things and would re-enable the injector where ce deliberately disabled
it. The ruling’s own premise (“an operator turned it off”) is one
decision about one product. And the daemon is the only side with a config
store, which is exactly how envfilter and envprecedence already ride
this file.
26.6 ★ The banner is NOT gated on the launcher
Section titled “26.6 ★ The banner is NOT gated on the launcher”Read the ruling’s dependency the way it is written: the banner exists because the launcher can be turned off. It is the channel that survives the launcher being off, and the operator who disabled the launcher is precisely the one who would otherwise never learn the licence lapsed.
So launcher_enabled: false skips the menu injector and leaves the
banner injector alone; they are siblings in one pipeline, appended
independently (shcinject.go). The switch deliberately does not live
in “whether ce attaches the middleware”, because that would take the
banner with it.
Getting this backwards is the single most likely way to ship this ruling
wrong, because backwards is also the arrangement that looks tidier: one
flag, one feature, off together. TestBannerSurvivesTheLauncherBeing
Disabled is the guard, and it asserts both halves on one response:
each half is already covered elsewhere and each would stay green under
the defect, because the defect is about the two together.
26.7 The ceiling
Section titled “26.7 The ceiling”menuPayloadByteCeiling 31,500 → 32,700, measured 32,227 served
bytes (31,180 + 1,047). The base was re-measured on main rather than
taken from §23.6’s 31,041: four launcher lanes landed in between, and a
lane that assumed the older number would have mis-stated its own cost by
139 bytes.
The 1,047 is one payload function (up()) plus three edits under 70
bytes: get()’s wire guard learning that an answer carrying sub and no
apps is valid (it previously discarded it, which would have shipped the
whole feature as a blank corner), build()’s fork, and skipping
dress()/home() on a pane with no tiles to arrange.
No copy rode the payload. All five sentences a refused user reads (heading, paragraph, command, anchor label, URL) arrive at runtime on the private inventory response, exactly as §23.5 requires.
27. The folder, driven (ruled 2026-08-18)
Section titled “27. The folder, driven (ruled 2026-08-18)”The owner drove his live launcher with a folder open and sent five
rulings in one sitting: four about the folder, one about the profile
chip. This section is the estate-facing record; the argument for each
line lives in traefik/plugin/menu_folders.go and menu_profile.go.
27.1 Drag-out was invisible: a clip, not a z-index
Section titled “27.1 Drag-out was invisible: a clip, not a z-index”Verbatim: “notice when i drag an icon off the folder it becomes hidden instead of showing on top of the folder.”
Two faults, one symptom, and the second would have bitten the moment the first was fixed:
| fault | why no z-index could have fixed it |
|---|---|
the board is overflow-y:auto | an overflow scroller clips its children to its padding box, and clipping is not a paint order; a child cannot escape an ancestor’s clip at any z-index |
the board is position:absolute; z-index:8 | that is a stacking context, so the held tile’s z-index:9 was resolved inside an 8 and could never out-paint the rename field (z-index 9, a sibling of the board) |
The fix is that the tile leaves the board. lift() reparents the
held anchor to the pane on the first millimetre of travel, freezing its
on-screen box first, pinning its width, setting H.r0 so the frozen-rect
reader does not fall through to a live rect that already carries the drag
transform, and re-taking pointer capture, because moving a node
between parents removes it from the document for the duration of the move
and the spec releases capture implicitly when that happens. gh() then
raises it to z-index:12, above the board (8), the rename field (9),
the scrim (7) and the header and field (1).
It runs for folder drags only. Lifting a field tile would remove it
from the grid, and removing a grid item reflows every tile after it,
under a finger, against the rects base() has just frozen.
Measured in Chrome 147 at 390×844 DPR3 with ShadowRoot.elementFromPoint
at the dragged tile’s own centre, the browser’s own hit test, through the
real paint order:
| step | before | after |
|---|---|---|
| inside the board | painted on top | painted on top |
| straddling the edge | painted on top | painted on top |
| half out | hit test returns the board | painted on top |
| fully out | hit test returns the board | painted on top |
27.2 Folders are translucent: the deliberate reversal of defect (c)
Section titled “27.2 Folders are translucent: the deliberate reversal of defect (c)”The owner wants to see the home screen through an open folder. Defect (c) was diagnosed one layer too coarsely: the original bug was a 63%-alpha board over the full-contrast springboard, and the fix that shipped (opaque board, 72% scrim) cured the collision by removing the see-through, which also removed the one cue that says there is a home screen outside this, and you can drop things on it.
Legibility moves to the backdrop, in three layers that degrade in order:
- the scrim dims less:
rgba(4,8,16,.38), not.72; - the scrim blurs (
backdrop-filter, both spellings, one value), so one filter frosts everything behind the whole overlay rather than a second compositing layer on the board; - the board is a light translucent card: a white alpha gradient with
the inset hairline
mkF()’s folder face already uses, so an open folder reads as the same object as the tile it grew out of.
With no backdrop-filter at all, layers 1 and 3 stand and the
springboard shows through unblurred. That is busier than intended and it
is still the thing that was asked for.
27.3 More room around the folder: and box-sizing is the margin
Section titled “27.3 More room around the folder: and box-sizing is the margin”Verbatim: “leave a bit more space around them so there’s more room and more obvious i can drag things off of it.”
The board was left:20 right:20 top:92 bottom:92. On a 390px phone that
is 20px of springboard either side, half a fingertip, nothing to drag
onto. It is now:
- width
78%, capped at430px, centred withleft:50% + translateX(-50%). On a phone that is 304px with 43px of home screen either side; on a desktop it is a 430px card, not a 1300px sheet. - height its own content,
top:120pxwithmax-height: calc(100% - 270px)instead of abottom.topplusbottomstretches an absolutely positioned box between them, which is how a two-icon folder came out 630px tall on a desktop; themax-heightkeeps the old floor as a cap and a fuller folder still scrolls inside itself. - box-sizing
border-box, and that is not decoration. Measured in Chrome at 390×844 before it went in: the declared82%resolved to a 344px board rather than 320, because the default content-box adds the 12px padding on each side. A geometry ruling whose number is silently 12px off on each side is a geometry ruling nobody can review.
27.4 Drag out and hold closes the folder; the continuity is the feature
Section titled “27.4 Drag out and hold closes the folder; the continuity is the feature”Verbatim: “when i drag off of it and hold off of it the folder closes and the app can still be dragged where i want on the home screen.”
Anything can close a folder. What the ruling asks for is a folder that closes without the gesture noticing: no cancel, no restart, no snap-back, and the tile still in the air afterwards.
- the trigger is the held tile’s centre leaving the board, not
the pointer’s position, because
cont()already decides the drop container from the tile’s centre, so the dwell starts at exactly the moment the drop target stops being the folder. - the dwell is 600 ms. iPadOS lands in the 0.5–1 s band. The floor is
accident-avoidance: a member carried across the board can leave and
re-enter its bounds in a couple of hundred milliseconds, and closing on
that would make in-folder reordering impossible near the edges. The
ceiling is the ruling itself; a hold you have to wonder about is a
hold you abandon. It is deliberately not 500 ms:
HDis the press-and-hold that arms a drag, and a second timer sharing that number would invite the two to be read as one gesture. - it is armed on transitions only. Crossing out starts it; crossing back in clears it. Moving around outside does not restart it; “hold off of it” is about staying out, not about staying still.
- the continuity is free, because of §27.1. By the time a dwell can
fire, the held tile is a child of the pane:
shutF()’s teardown loop cannot remove it, and a node that is never removed never loses its pointer capture. The folder is dismantled underneath a live gesture and the gesture is untouched. shutF()no longer saves while a drag is in flight. The held tile is parented to the pane, sosnap()cannot see it, and a save fired by the mid-gesture close would write (and POST to the daemon) an arrangement with that app missing. The release saves unconditionally a moment later.
Measured in Chrome at 390×844 DPR3: folder still open at t+484 ms after
the crossing, closed at t+786 ms, the same tile still held and captured
through both, dropped at the released slot, and exactly one POST to
/.shc/launcher/layout for the whole gesture.
27.5 The profile dropdown is deleted; the chip is a door
Section titled “27.5 The profile dropdown is deleted; the chip is a door”Verbatim: “i don’t want this dropdown menu on the floating menu. instead clicking the icon should take me straight to the console.”
The sheet, the scrim, the card, the “Signed in as” header, the Account
row and the note rows are deleted, not hidden. Every byte of them
was delivered to every anonymous visitor on every host of the estate. The
chip is an <a href> to launcherProfile.Console, the same URL
consoleHref() already resolves (the resolution shc!196 fixed when it
stopped resolve’s structural unentitled flag from skipping every
console tile), opened target=_blank rel=noopener and closing the panel
like every tile.
The edge cases keep their honest answer, which is absence.
buildLauncherProfile distinguishes four outcomes and only one ever
produced a live href:
| the daemon said | the sheet used to draw | the chip now |
|---|---|---|
| entitled, routed, openable | a Console link | the chip |
| entitled, nothing routed | ”not deployed on this estate” | no chip |
| licence refused / never licensed | the tier or trial sentence | no chip |
| unknown, or no role | nothing at all | no chip |
Keeping the chip and hanging the refusal off it was considered and
rejected: with no sheet the only place left for the sentence is a title
attribute, which a phone never shows, a pitch nobody can read attached
to a door nobody can open. The upgrade journey is not lost with it: an
estate that is merely unlicensed keeps its console and estate-settings
tiles (applyConsoleAccess removes them only for the ROLE refusal),
and §26 owns the pitch those lead to. Account and identity now live in
the console’s own top-left avatar menu.
The wire is unchanged on purpose. u, s and cn still ride the
private inventory response, which has no byte ceiling, because the
console’s own avatar menu is the surface those fields are moving to.
27.5.1 …and the door is the account profile (2026-08-21)
Section titled “27.5.1 …and the door is the account profile (2026-08-21)”Owner rule, applied to both surfaces at once: clicking the user profile
avatar (in the launcher and in the Console) opens the Keycloak account
profile, <issuer>/account/. The Console’s half is
features/console/src/springboard/AccountButton.tsx, whose avatar menu
gained an Account entry at the top; the launcher’s is the chip’s
href moving from p.c to p.s.
The shape §27.5 decided is untouched: one anchor, no dropdown,
target=_blank rel=noopener, closing the panel like every tile. Only the
destination moved, and the Console did not lose a door; it has a tile on
the grid with its own long-press menu into its screens (§28).
Why an avatar opens the account console. The chip is a picture of a
person. Every other affordance here names a place; the one that names a
human opens the human’s own settings (password, MFA, sessions), which is
per-user, ungated and present on every estate at every tier. The table
above therefore collapses: the chip is rendered exactly when p.s is
set, so a licence refusal, an un-deployed console and a silent daemon all
keep the identity affordance, and only an unresolvable realm removes
it. Absence is still never a guessed hostname.
And the URL is the caller’s own realm, from the daemon. ce publishes
account_url on GET /api/user/effective-apps (modules/user/types.go,
additive and omitempty, resolved through the AccountURLResolver seam
onto auth.Service.AccountConsoleURL, the same issuer the token iss
pin enforces). buildLauncherProfile prefers it and falls back to
accountURL()’s per-host realm lookup when it is absent.
That preference is a fix, not plumbing: the per-host lookup answers with
the realm of the host, which is wrong for anyone whose token came
from another one: a platform admin off master browsing tenant corp’s
app was pointed at corp’s account console, where they hold no account.
The fallback stays wired so an un-rolled daemon keeps the chip it has
today, and the preference skips the lookup rather than overriding it.
27.6 The tenant label next to app names
Section titled “27.6 The tenant label next to app names”Verbatim: “on the floating menu you don’t need to put the tenant next to the app names as it only shows from that tenant anyways.”
The one thing this launcher has ever printed next to an app name was a
parenthesised environment, appended by renderMenuApps whenever the
answered set spanned more than one. His reason applies to it exactly: the
surface is single-tenant by construction (§7 refuses any identity whose
tenant is not the host’s) and single-environment by his own 2026-08-17
ruling (§20), and dedupeMenuEnvironments already collapses every stack
to one tile by precedence, so the suffix annotated a choice the user
cannot see, cannot act on and did not make. It is gone, and
menuSpansEnvironments with it.
It frees wire bytes twice over on a response fetched once per page
view: the suffix itself, and a second copy of most names, because
" (staging)" pushes a label past menuCaptionMaxRunes and
captionEveryTile then ships the middle-ellipsis form alongside it. It
frees zero payload bytes: it is server-side Go, not injected script.
27.7 The defect found on the way: restored folders were dead
Section titled “27.7 The defect found on the way: restored folders were dead”all() walks the shelf, the pages and the OPEN board. A folder rebuilt by
apply() holds its members in F.items, detached (mkF() takes
them out of the tree), so at install time no board is open, all() cannot
see them, and the arming loop skipped every member of every restored
folder. They came back with no pointerdown handler: not draggable
inside the folder, not out of it, not onto the field.
It was invisible for a whole session, because a folder you had just made
was assembled from tiles gset() had already armed. It appeared on the
next page load, which is every page load, for a layout that persists to
the daemon on purpose. Reproduced in Chrome against the pre-fix payload:
the drag never started at all.
The arming loop now reaches inside the folders. It is done there rather
than inside mkF() because mk2() also calls mkF(), with two tiles
that are already armed, and gset() wraps A.onclick around whatever was
there before, so a second call on the same node would stack two wrappers.
27.8 prefers-reduced-motion, honoured for the first time
Section titled “27.8 prefers-reduced-motion, honoured for the first time”RM is asked once and gates the only animation this file has: base()’s
165 ms transform transition, which is what makes the neighbours slide
during a reorder. Under reduce the neighbours still move, and to exactly
the same places; the preview is the FUNCTION, the easing is the MOTION.
Nothing the four rulings add animates at all. Measured in Chrome with
prefers-reduced-motion: reduce emulated: identical displacement
(translate(-91.5px, 0px)), transition transform 0.165s → none 0s.
27.9 The payload budget
Section titled “27.9 The payload budget”| bytes | |
|---|---|
| before | 35,888 |
| after | 35,180 |
| ceiling (unchanged) | 36,000 |
The profile dropdown freed 1,764; the folder work, the reduced-motion gate and the arming fix spent about 1,056. The ceiling was not raised.
28. The panel header, as it actually ships (recorded 2026-08-18)
Section titled “28. The panel header, as it actually ships (recorded 2026-08-18)”§27.5 deleted the profile dropdown and left an identity chip in the panel
header. Nine minutes after that landed, a second lane landed the Keycloak
Log out control (traefik/plugin/menu_logout.go) into the same
header. Neither lane could see the other, so this section records the row
they add up to and the two things about it that nothing was holding.
28.1 The row
Section titled “28.1 The row”Left to right, and this is the order the code produces rather than a wish:
| child | built by | what it is |
|---|---|---|
| mark | build() | the SHC glyph |
| ”Applications” | build() | the panel title |
| identity chip | who(), menu_profile.go | an <a href> to the caller’s Keycloak account profile (§27.5.1), _blank/noopener, closing the panel. Present only when the daemon named the caller AND a realm resolved for them. |
| Log out | bye(), menu_logout.go | an <a href> to the sidecar’s /.shc/auth/logout on a gated host, or the realm’s end-session URL on an ungated one. Present only when the host has a logout route. |
| close X | build() | last child, by contract |
Both optional controls insertBefore(close), so their relative order
is decided by nothing more durable than the order build() calls them
in, and the close X stays last only because neither appends. The chip is
a door and belongs near the title; Log out is the only control in the
panel that destroys anything and belongs beside the way out.
Measured in Chrome 147 at 390x844 DPR3 against the served bytes, with a
wire carrying both me and o: chip at x=187..223, “Log out” at
235..316, close at 328..372, in a 390px header whose own margin is 18px.
They fit, in that order, on the narrowest phone the launcher targets.
28.2 What was holding it: nothing
Section titled “28.2 What was holding it: nothing”Every existing header assertion was true of a header with exactly one
of the two controls in it, because each lane’s fixture omitted the other
lane’s field; logoutInventory carries no me, inventoryWith carries
no o. “My parent is the header” and “close is last” both survive a
build where the chip vanishes the moment a host has a logout route.
TestTheHeaderCarriesBothTheIdentityChipAndTheLogoutControl
(menu_logout_node_test.go) renders both from one inventory and holds
four claims: both present, neither armed by the tile drag machinery,
chip-then-logout-then-close, and the chip’s href still the account console.
Proved by mutation: swapping build()’s call order, suppressing the
chip when D.o is set, blanking the chip’s href beside a logout control,
and arming the chip beside one each fail this test and no other test in
the package.
28.3 The budget, corrected
Section titled “28.3 The budget, corrected”§27.9 recorded 35,180 bytes. That was the truth of its own merge and
stopped being the truth of main nine minutes later, when the logout
control landed on top of it.
| bytes | |
|---|---|
| before §27 | 35,888 |
| after §27 (the folder work and the deleted dropdown) | 35,180 |
| after the Log out control | 35,505 |
| ceiling (never raised) | 36,000 |
Headroom on main is 495 bytes, not the 820 §27.9 implies. Anyone
spending against this budget should read this table, not that one. This
section costs zero payload bytes: it is documentation and a test.
29. The unreachable tile: greying what this network cannot open (built 2026-08-18)
Section titled “29. The unreachable tile: greying what this network cannot open (built 2026-08-18)”The owner’s question, verbatim:
“if an app is not public and i access another public app and open the floating menu will the public app show up greyed out? or if i’m in the console not from lan will it show those apps grayed out?”
The measured answer before this section was written was NO, on both
surfaces. renderMenuApps carried no exposure or reachability concept,
and the console’s springboard had no disabled state. Every entitled app
listed identically whether or not the viewer could reach it, and clicking
an unreachable one produced a bare 403 from the ipAllowList
middleware with nothing to explain it. This section is the build.
29.1 ★★ It is presentation. The middleware is the boundary.
Section titled “29.1 ★★ It is presentation. The middleware is the boundary.”Say this first because it is the thing most likely to be forgotten by whoever edits this next.
The enforcement is, and stays, the per-deployment ipAllowList
middleware ce/modules/app/lan_allowlist.go renders in front of a
restricted deployment’s routers. Nothing in this section grants or
withholds access:
- a greyed tile is still listed, still focusable, still openable, and is refused by the middleware if the viewer is outside the ranges;
- an un-greyed tile is refused by that same middleware under exactly the same rule. Absence of the mark is not permission.
Both code paths carry that paragraph at their top (traefik/plugin/menu_reach.go,
modules/console/reach.go) precisely where a future reader would be
tempted to move a check into them.
29.2 The mechanism differs per surface, and that is the crux
Section titled “29.2 The mechanism differs per surface, and that is the crux”| Launcher | Console | |
|---|---|---|
| Where the code runs | inside Traefik (yaegi) | a browser app + the daemon |
| Who the peer is | r.RemoteAddr is the browser | r.RemoteAddr is Traefik |
| Reads a forwarded header | never | yes; see §29.4 |
The launcher is nearly free. The plugin is a Traefik middleware, so
the request it answers arrived on the same TCP connection ipAllowList
judges, and LanAllowlistMiddleware declares no ipStrategy precisely
so that it reads the real peer rather than a client-sent header. The
plugin therefore re-decides a decision being made beside it, from the
same input.
The answer transfers across routers: the peer is a property of the connection, not of the hostname it asked for, so “would that app’s allowlist admit me” is answerable from the page the viewer happens to be standing on.
Measured against the live estate, 2026-08-18: bitspur/hel1 has the knob armed for one deployment:
| Probe | Result |
|---|---|
| the restricted host, from outside the estate | 403 |
…+ X-Forwarded-For: <an admitted node address> | 403 |
…+ X-Real-Ip: <an admitted node address> | 403 |
| the same host, from a node on the admitted plane | 401 |
an exposure: internet host, from outside | 200 |
The two spoofed 403s are the whole point: the deployed middleware reads
the connection, not the header. The 401 is the forward-auth gate
answering, which means the packet arrived, so the allowlist admitted it.
And a middleware that judges the true peer can only do so because Traefik
hands its middlewares the real RemoteAddr, which is exactly the input
the plugin reads.
29.3 What the daemon publishes
Section titled “29.3 What the daemon publishes”apps.json grows two additive fields (no version bump; the file’s
contract is that new needs are met by adding fields):
| Field | Where | Meaning |
|---|---|---|
lan | top level | the table of distinct enforced source-range sets, in first-use order |
lanset | per entry | 1-based index into lan; absent/0 means no restriction is rendered |
A table rather than a list per entry, and the reason is measured:
bitspur/hel1 derives 44 CIDRs for its one armed deployment and its
apps.json is 10,427 bytes for 54 entries. Copying the set onto
every entry would cost ~700 bytes each (a ~38 KB file on an estate that
armed the knob tenant-wide, rewritten and diffed by the 60 s sweep) to
say one thing 54 times. Two deployments genuinely can derive different
sets (lanAllowlistCidrs is scoped), so the table holds each distinct
set and no entry is ever pointed at a set that is not its own.
The daemon stamps this from LanAllowlistFor (the same function the
ingress reconcile calls to decide what the middleware enforces) on the
same node, in the same sweep. The published ranges and the enforced
ranges cannot drift because they are one call.
This is the same publish-the-policy / evaluate-the-viewer split that
envfilter and envprecedence already ride (§12.7): one apps.json
serves every viewer of every host, so anything per-viewer must be
evaluated by the side that holds the request.
29.4 The console: three honest options, and which was chosen
Section titled “29.4 The console: three honest options, and which was chosen”The console is a client-side app over an API, so it does not inherently know what its browser’s network can reach.
| Option | Verdict | |
|---|---|---|
| (a) | The daemon computes it from the request’s source address and stamps it on an inventory response | Chosen |
| (b) | The console probes each host | Rejected |
| (c) | No mark; explain the refusal when it happens | Kept as the fallback |
(b) is rejected on mechanics, not taste. A cross-origin fetch to a host the browser cannot reach does not fail fast (it hangs to a TCP timeout) and CORS makes success and failure indistinguishable from script anyway. It would also fire a real request at every app on the estate on every home-screen paint.
(a) carries a caveat that had to be measured. MEASURED on
bitspur/hel1 2026-08-18: the console is served through Traefik;
https://shc.hel1.hetzner.bitspur.com/ answers 200 on port 443
carrying x-shc-ratelimit: on, the daemon’s own header. So
r.RemoteAddr at the daemon is a docker-bridge address belonging to
Traefik, which is itself inside every derived allowlist. Answering from
RemoteAddr alone would tell every console viewer that everything is
reachable, a constant wearing a feature’s clothes.
shc.console.reach therefore reads X-Forwarded-For, which
LanAllowlistMiddleware explicitly refuses to do. The two are not in
conflict, because they answer different questions:
- the middleware is a control; a spoofable input there is an allowlist walkable from the open internet, so it must never read a header, and it does not;
- this route is a picture; the worst a spoofed value achieves is a wrong picture, for the spoofer, on their own screen. It cannot move what Traefik does, and the answer is computed per request and returned to that request alone, so it cannot reach another viewer.
A claim that stood here was false, and is recorded rather than quietly deleted. This section asserted that a browser cannot set
X-Forwarded-Forbecause it is a forbidden header name. It is not on the Fetch spec’s forbidden list. Measured in Chrome against a header-echo server, 2026-08-18: bothfetch(url, {headers: {'X-Forwarded-For': '10.236.16.9'}})andxhr.setRequestHeader('X-Forwarded-For', …)arrived at the server verbatim. The design survives (the two reasons above never depended on it), but an argument nobody checked is exactly how a real control ends up resting on one. What the spoof does buy is an oracle; see §29.8.
The header is believable on the deployed path because Traefik’s
websecure entrypoint declares no forwardedHeaders.trustedIPs: it
discards whatever the client sent and writes the observed peer itself.
The route reads the rightmost value for the general case (the only
entry in a chain a client could not have written) and falls back to
RemoteAddr when no header is present (a desktop shell talking straight
to the daemon).
(c) is the fallback rather than the design. When the viewer’s address
cannot be established the route answers known:false and the console
marks nothing, which is exactly (c).
29.5 ★ Unknown is not unreachable
Section titled “29.5 ★ Unknown is not unreachable”Every failure path renders the tile normally:
- no
lantable (a daemon that predates the field); - an entry with no
lanset(unrestricted, or underivable at the daemon;LanAllowlistForreturning an error publishes nothing); - a
lansetpointing outside the table (a torn or hand-edited file); - a peer address that will not parse;
- a set whose ranges will not parse.
The asymmetry is deliberate. A false grey is a working app the product
told the user not to click. It costs a user their app and teaches them
the menu lies. A missing grey costs one click and a 403, which is
precisely what every estate did before this shipped. The console’s wire
keeps known as a separate field for the same reason: “I checked and
everything is reachable” and “I could not check” are different
sentences, and an empty list only says the first.
29.6 How it is drawn, and why
Section titled “29.6 How it is drawn, and why”Two channels ship on both surfaces, and neither is the label:
grayscale(1)on the artwork, the thing a person recognises a tile by..45opacity on the picture (the launcher’s glyph node; the console’s glyph box).
The second channel exists because of what the first one missed. Driven in
a browser at 390×844 DPR3: grayscale alone left paperless
byte-identical to its reachable self (it ships a white feather) while
gitlab’s orange fox went obviously grey. One signal that a particular
icon defeats is no signal.
The caption is untouched. It is the only thing on a tile with a
contrast requirement, it sits on a wallpaper that is dark in both themes
(the launcher paints its own surface; see packages/springboard-ui/src/wallpaper.ts),
and dimming it to say something about the network would trade legibility
for a signal the icon already carries. No animation is involved, so
prefers-reduced-motion is unaffected.
A third channel was tried and removed. A dashed border was written,
shipped into a browser, and measured as border: none 0px on every tile:
dress()/home() re-style the anchor’s box when they lay the home
screen out, so the anchor’s own border never survives to paint. It was
deleted rather than left in as bytes that look like a feature.
A11y: the reason is in the accessible name, not only in the colour.
Both surfaces append , not reachable from this network to the tile’s
aria-label (and title on the launcher), beside the verb. aria-disabled
is deliberately not set: the tile is not disabled, it is unreachable,
and activating it is how a user learns what the boundary says.
29.6.1 What is deliberately not marked
Section titled “29.6.1 What is deliberately not marked”A tile’s right-click / long-press menu (k, sidecar stacks and vapp
instances) is not marked. It is a scope line, not an oversight, and
it degrades the safe way: an unmarked kid is a missing grey, exactly
the behaviour every estate had before this shipped. The bytes are the
scarce thing (a kid mark needs a wire field, a fold-time copy of the
parent’s lanset, and a branch in the compact arm() that paints the
menu), and a sidecar folds onto its parent precisely because it belongs
to the same app; the common shape is one exposure for the pair, and the
parent tile already carries the mark. menu_reach.go records how to
build it if it is ever wanted.
29.7 The byte cost, exactly
Section titled “29.7 The byte cost, exactly”menuPayloadByteCeiling is 36,000 and was not raised.
| Served payload bytes | |
|---|---|
| Before | 35,505 |
| After | 35,623 |
| Cost | +118 |
| Headroom remaining | 377 |
The wire cost is a single omitempty flag character (x) per marked
tile, and the launcher’s /apps response is same-origin, private and
no-store, so it is not what the ceiling bounds in any case. The
response carries the boolean only: never the ranges it was computed
from, which are the estate’s internal topology.
TestReachMarkNeverShipsTheRangesItWasComputedFrom holds that.
29.8 ★ The disclosure note, for the owner to rule on
Section titled “29.8 ★ The disclosure note, for the owner to rule on”Greying tells a viewer exactly which hosts are private.
The honest assessment is that this is a small leak, because the same
viewer can already derive the same fact by clicking: a reachable host
answers, an unreachable one answers 403. The mark converts an
n-click enumeration into a single glance, for a viewer who is already
authenticated, already entitled to the app, and already being shown its
name and hostname in the same menu.
It is recorded here rather than decided here. If the owner would rather
the launcher said nothing, the smallest reversal is to stop stamping
lanset in BuildAppsMenu; every reader already treats its absence as
“nothing is restricted”, so the marks disappear estate-wide with one
config-free change and no image roll.
The second disclosure is an oracle, and it is the console’s alone.
Because shc.console.reach believes X-Forwarded-For (§29.4) and a
browser really can set it (measured, above), a caller who already holds
the console’s Ops role can ask “would 10.236.16.9 be admitted?” by
sending it and reading which stacks come back, and so map the estate’s
admitted ranges without shc config get lanAllowlistCidrs.
Bounded, but real:
- the caller is authenticated and already entitled to the console
(
AccessFor(r).Ops, the read-only support floor); - the ranges are the estate’s own private networks and node addresses,
not a secret; the same operator can read
lanAllowlistCidrsthrough the config API; - the answer is never readable cross-origin: the daemon sets no CORS
headers at all (
ce/core/api/server.go, by design), so a hostile page cannot run this probe on a logged-in operator’s behalf; - it moves nothing. The
ipAllowListmiddleware is unaffected by any of it.
If you would rather close it, the route can read RemoteAddr only, at
the cost of the entire console half, which then marks nothing on any
estate that serves its console through Traefik, which is every estate
measured so far.
30. The springboard panel: read-only and server-rendered (ruled 2026-10-30, FZ-8492)
Section titled “30. The springboard panel: read-only and server-rendered (ruled 2026-10-30, FZ-8492)”The owner’s ruling: the floating panel on an app page is a read-only copy
of the console’s springboard. It looks like the springboard, it opens apps
and nothing else, and one link opens the full console in its own tab. It
ships no MPO bundle and no React. It sits behind launcher.panel until it
has run on corp.
30.1 Where it renders
Section titled “30.1 Where it renders”The Traefik plugin renders it at request time from templates a build step
generates out of the console’s own components. The plugin already proves
the caller and builds the per-user tile list for /apps, so the panel is
the same inventory written as a tree instead of JSON. Nothing new learns
the launcher handle, and there is no extra hop to the daemon.
make gen-launcher-panel runs packages/springboard-ui/src/launcherPanel.spec.tsx,
which server-renders LauncherPanel (the springboard’s Wallpaper,
StatusBar, SpringboardField, StackTile, ConsoleAppTile and Dock
under the console’s Tamagui config) at every width the springboard’s media
queries distinguish, in dark and light. It then:
- keeps the Tamagui and react-native-web rules the tree uses, rescoped from
:rootto:host; - turns every inline
styleinto a generated class, so no style attribute reaches the page; - folds the width and scheme variants into
@mediaoverrides, and fails if a variant changes the tree’s shape; - cuts Latin subsets of the console’s Inter 400 and 700;
- writes
traefik/plugin/panel_gen.go: the shell, the tile and dock templates, the CSS, the fonts and the monogram fixture.
A stale panel_gen.go fails that spec. The monograms and hues are a Go
port of resolveMarks, checked against the whole catalogue
(TestPanelMarksMatchTheConsole). The stored layout orders the field and
the dock the way the console does. A folder’s apps take the folder’s place
in the field, one tile each; the panel draws no folder tile yet.
30.2 Endpoints
Section titled “30.2 Endpoints”This widens the reserved /.shc/launcher/ set by two paths.
| path | answers |
|---|---|
GET/HEAD /.shc/launcher/panel | the panel as a JSON element tree, private, no-store, gzip when asked. Same credential ladder and the same byte-identical 401 as /apps; the subscribe and grantless answers and an unarmed tenant get that 401 too. |
GET /.shc/launcher/panel/<sha256 prefix>.{css,woff2} | the stylesheet and the two font subsets, content-addressed, public, max-age=31536000, immutable, no identity. |
The tree carries the tenant name and, per tile, the name, caption, link,
icon and monogram. It carries no profile, logout link, layout token, handle
or token (TestPanelAnswersOnlyTheAppList). Every other method is 405.
“Open console” links to the tenant’s console route, read before the console
role gate, so a caller below tenant:read gets the link too; the console
decides what that caller sees. Only a tenant with no console route gets an
empty link, and the panel CSS hides an empty link
(TestPanelOpenConsoleShowsWhateverTheCallersConsoleRole, FZ-9214).
30.3 The loader
Section titled “30.3 The loader”/apps answers pn: 1 when the host’s tenant has launcher.panel: springboard. A press, or a hover, focus or touch on the trigger before
it, fetches /panel, the CSS and both fonts in parallel. The loader
adopts the CSS as a constructed stylesheet on the launcher’s shadow root,
registers the fonts with FontFace from an ArrayBuffer (Chrome ignores
@font-face inside a shadow root, and a buffer is not a font-src load),
and builds the tree with createElement, so a Trusted Types page doesn’t
throw. It sets the date and time, focuses close, and puts a tile’s monogram
back if its icon fails. A tile or the console link closes the panel as the
new tab opens. A non-200, a missing CSSStyleSheet or a 4 s timeout drops
to the drawn grid, as before.
30.4 The knob
Section titled “30.4 The knob”launcher.panel is menu (the shipped default, the drawn grid) or
springboard, global or tenant scope, live. The daemon stamps the
resolved value as panel on each of the tenant’s apps.json entries.
shc config set launcher.panel springboard -t corp --scope tenantRollout: corp first, then the other tenants, then the global default.
FZ-8531 retires /layout and its write token after Ogden’s global switch
to springboard on 2026-11-03. Retiring the drawn grid, the shell slot
(§18-19) and the knob remains separate work.
30.5 The byte cost
Section titled “30.5 The byte cost”| Served payload bytes | |
|---|---|
| Before | 39,444 |
| After | 41,962 |
| Cost | +2,518 |
| Ceiling | 42,022 |
The cost is the JSON-to-DOM builder, the loader with its font and icon handling, the clock, the three asset names and the prefetch. It comes back with about 25 KB more when the drawn grid retires.