The branding socket: estate-wide logos as a magic capability
Archived, superseded by Branding is S3-only, served by shcd.
The branding socket: estate-wide logos as a magic capability
Section titled “The branding socket: estate-wide logos as a magic capability”Status: design document, revision 3: proprietary placement (owner ruling).
Revision 2’s “ruled CE at implementation” was an implementer default, not an
owner ruling, and the owner overruled it on review (2026-08-07): branding is
proprietary, shc-side. ce keeps only nameless mechanism (generic
RegisterMagicProvider / RegisterSystemApp init hooks) and the module, the
store app package, and the token registration all live in shc, entitlement-
gated per §8. Sections below marked [r3] carry the change; [r2] marks
survive where still accurate.
Previously: revision 2: implementation in flight. Revision 1
was produced from the 2026-08-06 design conversation (“logo” session) with ce
internals anchored only through shc tests. Revision 2 folds in a six-surface
recon of the live ce tree (2026-08-07) that overturned five revision-1 claims;
each correction is marked [r2] inline: the app package must be a ce
builtin/ system app (the master-tenant guard structurally refuses anything
else), the magic token must carry an EMPTY OverrideField (a non-empty one
hard-clobbers --var brand selection), the v1 bundle needs a raster twin
(GitLab cannot serve SVG), the server port is 80, and minted connection values
land in the SOCKET namespace, not plug data.
The question this answers: how does an operator get their own logo (and later, favicon, colors, product name) into every app in the catalogue? The answer is the same split the catalogue already uses for SSO (a dumb universal provider and per-app intelligence in plugs) plus the magic-token mechanism that already lets every tenant share the one master Keycloak.
0. Ground truth: existing facts this design leans on
Section titled “0. Ground truth: existing facts this design leans on”G1. Sockets name capabilities, and the stem is forever.
docs/app-development/plugs-and-sockets.md (“Naming a socket”): “A socket is
named for the wire protocol or contract it serves, never for the product that
serves it, never for the outcome it achieves”, and “renaming one later is a
migration, not an edit”; the stem is carried by every published registry
archive and every integration row on every installed estate. The doc’s
operational test: a capability stem must support a nameable external-<stem>
shim.
G2. Exactly one magic provider exists today: KEYCLOAK.
tests/unit/modules/app/integration_magic_test.go:73:
MagicProviderByToken("KEYCLOAK") → {Stack: "keycloak", OverrideField: "realm"}, provider tenant = auth.MasterRealm. Bare -i KEYCLOAK, -i oidc=KEYCLOAK, and the lowercase stack alias keycloak all resolve
cross-tenant to the master-tenant system Keycloak (:28-31);
KEYCLOAK@staging stays literal (:187); unknown all-caps tokens are NOT
magic (:33). OPENOBSERVE was deliberately removed and
tests/unit/daemon/otel_grammar_test.go:445 guards its return; telemetry is
fabric-only. So there is no “OTEL socket” precedent; KEYCLOAK is the whole
precedent, and it is enough.
G3. The consumer scopes itself within a shared magic provider via a plug
field defaulting to the tenant.
apps/gitea/oidc.plug.yaml:7: realm: "{{ vars.keycloak.realm | default(tenant) }}". Every tenant plugs into the one master Keycloak; the
realm field (the magic entry’s OverrideField) is what keeps them apart.
G4. Provider jobs can mint values back into the live integration data.
apps/keycloak/oidc.socket.yaml:260: the
::shc-connection-value::<key>=<value>:: marker, harvested by
parseConnectionValues, lands provider-side job output under the plug’s render
namespace. This is how a generated client secret reaches the consumer; it works
for any resolved value.
G5. Integration jobs re-run on the shared deploy path and are the natural
reconcile point. runSocketIntegrationJobs (modules/app/socket_jobs.go)
runs phases 1–2 on every consumer install/update; the gitea plug’s reconcile
branch leans on exactly this (apps/gitea/oidc.plug.yaml, “the job re-runs on
every consumer install/update”). Phase 3 (post_deployment) runs
consumer-side; phase 4 (unintegration) runs consumer-plug jobs before
provider-socket jobs.
G6. Later-added socket keys are additive, guarded consumer-side.
apps/keycloak/oidc.socket.yaml:69-72: provider-specific keys must be read as
integration.socket.data.<key> | default('') because a second provider serving
the same stem (external-oidc) publishes no such key. version and publicUrl
were both retrofitted this way without breaking a plug.
G7. One noun, composed per-app at the render site.
docs/reference/sso-display-name.md: the catalogue stores the provider noun
(keycloak.displayName) and each app’s render site composes whatever shape the
upstream field wants (bare label vs whole caption). Brand facts follow the same
doctrine: store the fact once, compose per app.
G8. State vs config. Assets an operator uploaded cannot be re-derived, so they are STATE by the taxonomy (needed for restore) and must ride backup.
1. The decision in one paragraph
Section titled “1. The decision in one paragraph”A new capability socket, stem branding (never logo; see §2), served by
a small branding system app in the master tenant: a static file server
over one volume holding a registry of named brands. A new magic token
BRANDING with OverrideField: "" [r2] resolves -i branding=BRANDING
cross-tenant to it, exactly as -i oidc=KEYCLOAK resolves to the master
Keycloak. The empty override is deliberate: ce’s cross-tenant override site
(ce modules/app/integration_render.go:605-616) stamps
PlugData[OverrideField] = <consumer tenant> UNCONDITIONALLY over whatever the
plug rendered, including an operator’s explicit --var branding.brand=acme,
so a "brand" override would make §6’s brand-selection promise false for every
non-master tenant. Keycloak’s realm override is a security compartment; brand
assets are non-secret (§3), so branding needs no compartment and the plug’s
default(tenant) template alone provides the scoping. Operators manage brands
with shc branding set|list|delete. Each
consumer app ships a branding.plug.yaml whose brand field defaults to
the tenant name (G3’s realm pattern); the provider’s integration job resolves
that name against the store, falling back to the brand named default, or to
a no-op when the store is empty, and mints the resolved brand + a content hash
back through the connection-value channel (G4). The consumer’s
post_deployment job fetches the bytes over the overlay and applies them by
whatever mechanism that app has. Unplugging restores the upstream look.
V1 carries exactly one brand fact: the logo, as logo.svg and/or
logo.png. [r2] The raster twin is forced by GitLab: its appearance
uploaders accept SVG at the API but SAFE_IMAGE_EXT excludes it, so an SVG is
served with attachment disposition (a broken image on the sign-in page) and
the omnibus container carries no rasterizer to convert with. The stem is
branding because the stem is forever (§2); the bundle, the CLI, and the
schema start with the logo alone and grow additively (§5).
2. Why branding, not logo
Section titled “2. Why branding, not logo”- G1 makes the stem permanent: a
logosocket becomes a rename-migration the day favicon or colors land.brandingabsorbs every future brand fact (favicon, palette, product name, login background, email footer) without touching the contract’s identity. brandingpasses the naming doc’s own tests: it names a capability, not a product or an outcome, andexternal-brandingis trivially nameable: a shim app that runs nothing and publishes URLs to brand assets an operator hosts elsewhere (their CDN). If that shim ever exists it serves the same stem, and a consumer cannot tell which is on the other end. That indistinguishability is the feature (G1’s mariadb/mysql argument).
3. The provider: a branding system app
Section titled “3. The provider: a branding system app”A minimal static HTTP server (one service, one volume) in the master tenant.
[r2] Placement is forced, and install is on-demand, not at init. The
master-tenant guard (ce modules/app/master_tenant_guard.go:157-174) refuses
any app outside SystemAppSpecs with X403978SYSTNT, and rule 3 additionally
refuses foreign packaging, so branding CANNOT be a regular catalog app; it
must live in ce builtin/branding/ beside the four existing builtins, ride the
deb, and gain a SystemAppSpecs["branding"] entry (empty spec). It is however
NOT added to systemAppInstallOrder: the init marker means existing estates
would never auto-install it anyway, and a consumer’s -i branding=BRANDING on
an estate without the stack already refuses cleanly with X404906STKNOF plus
the hint “install the dependency first with shc install branding -t master”,
exactly the on-demand UX. Auto-install at genesis is a two-line upgrade later.
[r3] The install must name the app, not a path. Measured live: shc install /path/to/branding -t master is refused with X403978SYSTNT, because
the master-tenant guard’s third rule admits only SHC’s own packaging (builtin
repo or a shipped static root) and treats an explicit source as foreign. The
operator spelling is the bare catalog name (shc install branding -t master)
which is also exactly what the missing-provider hint prints, so following
the hint always works.
The volume holds one directory per brand:
/brands/<name>/logo.svg # gitea and most file-drop consumers/brands/<name>/logo.png # raster twin, gitlab & friends [r2]The layout is a directory per brand, not a file per brand, precisely so future
facts (logo-dark.svg, favicon.ico, a brand.yaml for the display noun and
colors) are new files in an existing shape rather than a store migration. The
bundle hash (§5) covers whatever the directory contains, so change detection
never needs to learn about new asset types.
- Served on the overlay for integration jobs to fetch. [r2] Public serving
via
url('branding')is DROPPED from v1: no v1 consumer reads it, and the system-route materializers cover only keycloak/openobserve; a public branding route is new work that lands with the first reference-mode plug, per §5’s no-key-before-a-consumer rule. - Nothing in a brand bundle is ever secret. Brand assets render on
unauthenticated login pages by definition; the store needs no secret
handling, and no secret may ever be added to the bundle. This is also why
one tenant naming another tenant’s brand in
vars.branding.brandis a non-event, not a leak. - The store keeps no per-consumer state: connect writes nothing provider-side, so disconnect has no provider-side teardown (§6).
- Brand assets are STATE (G8): the app carries a
backup.yaml.
4. The CLI
Section titled “4. The CLI”shc branding set acme --logo ./acme.svgshc branding listshc branding delete acmeset upserts a named brand into the store via the daemon; the brand named
default is the estate-wide fallback. --logo is the only v1 flag; it is
repeatable and extension-detected [r2] (.svg → logo.svg, .png →
logo.png, ≤1 MiB each, anything else refused) so one invocation can carry
both the vector and the raster twin. Future brand facts arrive as new flags on
the same verb writing new files into the same directory (--favicon,
--logo-dark, --name, --color, …), no schema event, no new verb.
[r2] Mechanically: the CLI base64s the files into a JSON PUT /api/method/shc.branding.brand/{name} (the vault import/export wire shape);
the daemon, after a master-tenant gate, a strict slug check on the name (it
becomes a filesystem path segment), a filename allowlist, and the size cap,
writes them atomically into the branding deployment’s mounts/brands/<name>/
directory. App volumes are host binds, so no docker exec is involved and the
store is writable even while the stack is stopped. V1 assumes the daemon node
hosts the branding deployment (true for system-stack placement); multi-node
forwarding rides the existing internal-RPC family later.
If white-labeling is ruled an EE entitlement (open question, §8), shc branding set is the single natural gate point.
5. The socket contract
Section titled “5. The socket contract”# ce builtin/branding/branding.socket.yaml [r2: builtin, port 80, no publicUrl]schema: plug: brand@string: Brand to apply, defaults to the consumer's tenant name; provider falls back to 'default' socket: internalUrl@url!: Overlay origin integration jobs fetch bytes from resolvedBrand@string: Minted by resolve-brand, the brand dir that exists for this edge (empty = unbranded) hash@string: Minted by resolve-brand, 16-hex content hash of the resolved bundledata: internalUrl: "http://{{ environment }}.branding.{{ stack }}:80"Deliberately small. Two rules govern growth:
- Additive keys only, guarded consumer-side (G6): future keys
(
primaryColor,productName, …) are optional and read with| default(''), becauseexternal-brandingmay serve the stem without them. - No key lands before a plug consumes it. The socket key is the cheap
half; the real cost of every brand fact is the per-app fan-out to apply
it. A key nobody reads is contract surface carried forever (G1). Day-one
scope is the logo, full stop; it is what the two proof plugs (§7) apply.
Favicon, dark variant, product name, and colors each land with the first
plug that reads them (a
variantplug field arrives with the dark logo, a color key with the first app that has a theme knob to feed).
Per-brand values (the resolved brand name, the bundle hash) are NOT in socket
data; socket data is provider-static, but resolution is per-edge. They
travel through the connection-value channel instead:
jobs: integration: - name: resolve-brand context: service service: branding environment: BRAND: "{{ integration.plug.data.brand }}" command: | set -eu # Requested brand, else 'default', else no-op (app keeps upstream look). RESOLVED="$${BRAND}" [ -d "/brands/$${RESOLVED}" ] || RESOLVED=default if [ ! -d "/brands/$${RESOLVED}" ]; then echo "no brand for $${BRAND} and no default; branding is a no-op" echo "::shc-connection-value::resolvedBrand=::" exit 0 fi # [r2] Hash over RELATIVE paths (cd first): the daemon's `shc branding # list` replicates this formula in Go against the HOST-side bind path, # and absolute paths would put different strings into the digest on # the two sides. HASH=$(cd "/brands/$${RESOLVED}" && find . -type f | sort | xargs sha256sum | sha256sum | cut -c1-16) echo "::shc-connection-value::resolvedBrand=$${RESOLVED}::" echo "::shc-connection-value::hash=$${HASH}::"Fallback lives provider-side (only the store knows what exists); the hash gives every plug a cheap no-op check on the reconcile re-runs (G5).
6. The consumer plug
Section titled “6. The consumer plug”# apps/<app>/branding.plug.yamlservices: - <app service>data: brand: "{{ vars.branding.brand | default(tenant) }}" # G3, realm patternTwo consumption modes; copy mode is the default:
-
Copy mode: the plug’s
post_deploymentjob reads the minted values and fetches bytes fromintegration.socket.data.internalUrl, then applies them by whatever mechanism the app has: file drop into gitea’s custom assets dir (/data/gitea/public/assets/img/, root-image variant), a singlegitlab-rails runnerAppearance assignment for GitLab [r2] (the REST appearance route exists in CE but clearing has NO API route, and the PAT dance costs a second Rails boot; one rails runner does both directions), a Keycloak theme, a custom-CSS mount. Robust, works without public serving, self-heals on every deploy via the hash.[r2] Namespace correction: minted connection values fold into the SOCKET namespace, never plug data,
integrations.<plug>.socket.<key>in hook renders,integration.socket.data.<key>in plug-job renders (tests/unit/modules/app/socket_jobs_conn_test.go:61-81,mailcow_template_mapping_test.go:1125). Revision 1’sintegration.data.resolvedBrandspelling existed in neither namespace. -
Reference mode: for the few apps whose config accepts a logo URL, render a published URL directly. Cheaper and live-updating, but couples the app’s login page to the branding app being up and public, deferred until the first such plug, together with the
publicUrlkey and its ingress route (§3).
unintegration restores the upstream default (delete the dropped files, PUT
the empty appearance). Per G5’s ordering the consumer’s jobs run first and the
provider has nothing to tear down; the store holds no per-consumer rows, so
disconnect is structurally clean. Note the existing repoint caveat applies
unchanged: -i branding=other over an existing edge upserts without running
the old edge’s teardown; only -i branding! or uninstall de-brands.
Connect grammar, all existing (G2): -i branding=BRANDING (explicit), bare
-i BRANDING (auto-match, fine for any app with one matching plug),
--var branding.brand=acme to override the tenant default.
7. Rollout
Section titled “7. Rollout”-
ce: the
BRANDINGmagic token (OverrideField: ""[r2]) beside KEYCLOAK plusSystemAppSpecs["branding"]; thebuiltin/branding/package (nginx-alpine static server, port 80,brandsvolume, socket + backup.yaml); themodules/brandingCLI/RPC module with blank imports in bothcli/imports.goanddaemon/imports.go. shc [r2]: builtin packaging plumbing (BUILTIN_APPS,.gitignore,.goreleaser.yamlpayloads,deb-payload-check.sh), thetests/builtin/branding/bats suite, and twin unit tests extendingintegration_magic_test.go. -
Two proof plugs at the mechanism extremes before any fan-out: gitea (file-drop into the custom dir, no restart; the layered assetfs resolves per request) and gitlab (
gitlab-rails runnerAppearance assignment [r2]). These validate the contract, the fallback, the hash no-op, and both mechanism classes. -
Catalogue fan-out, triaged like the SSO campaign: expect native mechanisms for many, CSS/asset hacks for some, and a structurally can’t bucket. Each plug gets a per-app licensing check; several upstreams gate white-labeling behind paid tiers (SonarQube whitelabel and Grafana white-labeling are Enterprise features), and some licenses carry trademark/branding-removal clauses. Plugs set the operator’s logo where the app supports operator branding; they never strip upstream branding by asset-hacking around a paywall.
★ A FOURTH BUCKET, found 2026-08-07: license refuses at EVERY tier. The three buckets above all assume the answer is a mechanism question. It is not always.
apps/difycan never be white-labelled, by anyone, at any tier. Its license states you “may not remove or modify the LOGO or copyright information in the Dify console or applications”, scoped to the frontend, theweb/directory, i.e. thedify-webimage the package ships (apps/dify/app.yaml, the LOGO AND COPYRIGHT condition). The restriction is not conditional on who operates it, or on what anybody has paid; there is no Dify tier and no SHC tier that unlocks it. So the correct dify branding plug is no plug: not “structurally can’t” (a mechanism gap that a later mechanism could close), but “must not”, which nothing closes. Any triage sheet that only has a mechanism axis will mis-file this app.And it collides with what SHC sells.
TIERS.mdlists “white-label branding” as a Pro tier feature, so a paying Pro customer meets one catalogue app that refuses a feature they bought, with nothing warning them in advance. Owed: a tier-facing exclusion note (an owner call on sales copy, not an implementer’s edit). Recorded on the license side indocs/guide/apps/licensing-postures.md§“Branding restrictions that outlive every tier”.
8. Open questions
Section titled “8. Open questions”- EE entitlement or CE? OWNER-RULED PROPRIETARY [r3], superseding r2’s
CE default. The whole payload (store app, CLI/RPC module, token
registration) lives shc-side, beside license-broker, the same home as the
support_bundle/mcp rulings. ce keeps only nameless mechanism: the
RegisterMagicProviderandRegisterSystemAppinit hooks (the launcher precedent; payload sitting ungated in the AGPL repo is a defect class; outweighs packaging convenience; the master-tenant guard’s builtin requirement is met by shc’s own trackedbuiltin/branding/via local-first staging). Entitlement split, enforced at theshc branding set|deleteRPC:branding: pro-and-up (every paid tier except hobby): the single estate-widedefaultbrand, your own logo everywhere.white_label: top tier (enterprise) only: named per-tenant brands, the reseller story. (“flagship” is an app classification (full-integration apps, available on every paid tier) never a pricing tier.) Unlicensed = CE-equivalent per the trial contract: no token, no verbs, plugs no-op. Edge-gating on existing integrations is deliberately NOT done; a lapsed license does not tear branding out of running apps.
- Zero-touch auto-connect. Magic tokens still require
-iat install. The flagship zero-touch bar suggests branding plugs should eventually auto-connect whenever the store holds a matching brand, but that is a new default-integration mechanism affecting every socket, a separate proposal, and explicitly not smuggled in here. - Launcher. SHC’s own launcher is the one surface we fully control; it should consume the same socket rather than grow a parallel branding path. Sequencing depends on the launcher’s tier placement.