Mobile apps: proposal, owner design conversation 2026-08-16
Status: open design. Some items are ruled, and the console Hobby-gate premise is still awaiting a new ruling. Items marked (ruled) or (decided) were decided by the owner in the 2026-08-16 design conversation. Items marked (recommendation) are this document’s argument and are not decided. Items marked ★ NEEDS OWNER RULING either contradict a standing ruling or correct a premise the owner stated, and must be answered before build.
Amended 2026-08-16 (later the same day): the platform matrix is recorded as decided (§8.3) and the app review strategy with it (§9.6, including the demo-cluster gate as owed build work). ★ And §10.0 flags a ruling made on a WRONG PREMISE: the console was gated to Hobby on the belief that it was “born paid” and therefore additive, which the tree contradicts. That one is NOT resolved here: it needs the owner to re-decide (§12 Q5).
Companions landing today:
../decisions/2026-08-16-marketplace-identity-and-install.md ·
../decisions/2026-08-16-portal-cluster-identity.md ·
../decisions/2026-08-16-marketplace-entitlement-and-licensing.md.
Standing surface architecture:
2026-08-14-console-architecture.md ·
2026-08-14-portal-architecture.md ·
2026-08-14-marketplace-architecture.md.
0. ★ The greenfield premise is wrong: corrected before anything else
Section titled “0. ★ The greenfield premise is wrong: corrected before anything else”The owner asked this to be re-verified and said to speak up if scaffolding was missed. It was. The correction is large enough that it reshapes the proposal, so it goes first.
0.1 What the scan actually found
Section titled “0.1 What the scan actually found”Run against a fresh clone of main (a66f798a7), whole tree, .git excluded:
| Looked for | Found |
|---|---|
AndroidManifest.xml | none |
*.xcodeproj / *.xcworkspace / Podfile / *.entitlements | none |
pubspec.yaml (Flutter) | none |
capacitor.config.* / Cordova / NativeScript / Ionic | none |
*.webmanifest / manifest.webmanifest / site.webmanifest | none |
service worker (sw.js, service-worker*, workbox*, vite-plugin-pwa) | none |
beforeinstallprompt, display: standalone | none |
| React Native | ✅ react-native 0.83.2, pinned in the root pnpm.overrides and in two workspace apps |
| Expo config | ✅ apps/console/app.config.js and apps/marketplace/app.config.js |
| iOS/Android build lanes | ✅ prebuild:ios, prebuild:android, one run:ios, one run:android, plus root pnpm ios / pnpm android |
So the accurate statement is:
Greenfield on PWA. Not greenfield on native.
There is no PWA of any kind anywhere in the repo: no manifest, no service worker, no install affordance. That half of the premise is confirmed.
But apps/console is already a declared iOS and Android application. Its
app.config.js reads, verbatim:
platforms: ["ios", "android"],ios: { bundleIdentifier: "com.selfhostedcloud.console", supportsTablet: true },android: { package: "com.selfhostedcloud.console" },plugins: ["vxrn/expo-plugin"],There is no AndroidManifest.xml in the tree because there is not supposed
to be one: one prebuild generates the native projects from
app.config.js on demand, and the generated android/ and ios/ trees are
build output, not source. Searching for AndroidManifest.xml in an Expo-style
prebuild project is searching for a compiler artifact. The scan was correct and
the conclusion drawn from it was not.
apps/marketplace is the same shape and still carries template residue:
com.marketplace.app for both bundle id and package, the exact identifier
console-architecture §1 ruled must never ship.
Beyond mobile, apps/console also carries Tauri (src-tauri/,
tauri:build) and GNOME (vite.config.gnome.ts, gjs).
0.2 What this changes
Section titled “0.2 What this changes”There is already a ruling on all of it: console-architecture §8:
Build lanes: web is the only released target. iOS/Android/GNOME/Tauri/ VS Code lanes stay in-tree and CI-typechecked as insurance and the multiplatform.one showcase; revisit promotion after the Portal ships.
So the question in front of the owner is not “should we build mobile apps”. It is:
Should the console’s already-existing, already-typechecked native lanes be promoted from insurance to product, and if so, on which platform, and does a PWA get there first and cheaper?
That is a materially cheaper question than the one asked, and it has a different answer, because the marginal cost of the Android lane is not “build an Android app”; it is “add the one Android-only feature and take on a release channel”. §7 follows the argument from there.
One further correction while the premise is being fixed: the owner said “the
portal app”. The portal is Frappe: portal-architecture §9, “All
portal-side logic on Frappe. The owner explicitly declined a separate Go broker
service.” There is no apps/portal workspace package and no portal native
lane. The two apps are therefore not two symmetrical builds: the console
has native lanes today and the portal has nothing. See §1.3.
1. Two apps, not one (ruled)
Section titled “1. Two apps, not one (ruled)”RULED: a CONSOLE app and a PORTAL app, never one app.
1.1 The sharp reason: they authenticate against different IdPs
Section titled “1.1 The sharp reason: they authenticate against different IdPs”Not “they do different things”. The boundary is an identity boundary:
| Portal app | Console app | |
|---|---|---|
| IdP | our Keycloak | the customer’s Keycloak |
| Realm | our central realm | that cluster’s tenant realm |
| Server | one, always the same, ours | a different server per user, theirs |
| Discovery | a fixed, compiled-in issuer | discovered at setup, per connection |
| Trust root | our TLS chain | the customer’s, possibly a private cluster CA |
| Token lifetimes | ours, uniform | theirs, per realm, unknown to us |
| Who can revoke | us | the customer, unilaterally |
An app holding both credential sets straddles exactly the boundary the L2
compliance seal protects. From
../decisions/2026-08-16-portal-cluster-identity.md
§4.1:
A compliance control the restricted party can flip is theatre.
The seal is real because we hold no admin credential on the customer’s Keycloak, and sealing is “the customer deleting one IdP entry” (§4.1). A single binary that holds a live session against our IdP and a live session against the customer’s cluster is a process in which those two credentials are one memory-safety bug, one logging mistake and one shared keychain group apart. It does not break the seal on paper. It makes the seal a claim about our code quality rather than a claim about what we structurally cannot do, and that substitution is precisely what §4.1 refuses.
1.2 The consistency check this yields
Section titled “1.2 The consistency check this yields”A sealed cluster’s console app keeps working because it never talked to the portal.
This falls straight out of the split and is the cheapest available proof that the boundary is drawn in the right place. It matches, and extends to mobile, the properties portal-cluster-identity §4.3 already records as surviving L2: the machine install channel survives because “the install channel carries no human” (§1.5), and purchase approval survives because the approver acts in the portal, not on the cluster (§4.3). Add a third:
The console app survives L2, because it authenticates to the cluster and only to the cluster.
If a future change made the console app depend on a portal session for any non-optional function, that change would have silently broken an L2 seal. This sentence is the regression test for it, and should be carried into the mobile acceptance criteria as a named property, not left as prose.
1.3 ★ The asymmetry the ruling does not yet cover: NEEDS OWNER RULING
Section titled “1.3 ★ The asymmetry the ruling does not yet cover: NEEDS OWNER RULING”“Two apps” reads as two equal builds. The repo says otherwise:
- Console app: exists. React Native 0.83, correct identifiers, iOS+Android
prebuild lanes, CI-typechecked, screens already written (
features/console/srcStacksScreen,StackDetailScreen,AppsScreen,EventsScreen,SettingsScreen,MarketplaceScreen, plusdaemon/installApp,launcher/menu). - Portal app: does not exist in any form. The portal is a Frappe bench (portal-architecture §9) and shares no code with the multiplatform.one workspace.
And there is a third central product with a native lane nobody has ruled
on: apps/marketplace, which has its own app.config.js declaring iOS and
Android. The three-surface story is Portal · Marketplace · Console
(console-architecture header). So “two apps” leaves the marketplace’s native
lane unaddressed.
Question for the owner: is the marketplace’s native lane (a) folded into
the portal app as a tab, (b) killed and its app.config.js deleted so it stops
implying a product, or (c) a third app? (b) is the recommendation; the
marketplace is a storefront on our domain reached by top-level navigation
(marketplace-identity §5), which is the one thing a browser does best.
2. ★ Multi-cluster: this contradicts a standing ruling. NEEDS OWNER RULING
Section titled “2. ★ Multi-cluster: this contradicts a standing ruling. NEEDS OWNER RULING”The owner ruled today that the console app needs multiple connections, an SSH-client host list, each with its own realm and tokens.
Console-architecture §7 rules the opposite, and rules it in both surfaces:
Strictly single-cluster, in both web and native. “You can login to different consoles from the portal but from console you can’t switch to another console.” Cross-cluster navigation is exclusively the Portal’s job (link-out). No connection switcher anywhere in the console.
The phrase “in both web and native” is not incidental; it was written to pre-empt exactly this request. This proposal will not quietly overwrite it.
2.1 Why the two rulings can be reconciled, and on what terms (recommendation)
Section titled “2.1 Why the two rulings can be reconciled, and on what terms (recommendation)”The reason §7 exists is a session reason: a console web page that can switch clusters is a page that holds, or can be made to hold, more than one cluster’s credentials in one origin, and the portal already owns cross-cluster navigation, so the switcher buys nothing and costs a boundary.
On a phone that reasoning does not fully transfer, for one concrete reason: there is no portal tab to hop from. The web console’s §7 is livable because the portal is one browser tab away and can log you into any console. An installed app with no connection list is an app the user must delete and reconfigure to look at their second cluster.
So the recommended reconciliation is a narrowing, not a reversal:
- §7 stands unchanged for the web console. No switcher, ever.
- The native/installed console gets a connection list: an address book,
the SSH-client analogy the owner used, which is exactly right:
~/.ssh/configlists hosts; it does not log into all of them at once. - Hard property: exactly one connection is active at a time. Switching connections is a teardown and a re-establish, not a merge.
- No aggregate views. Ever. No combined stack list, no combined health, no fleet screen, no cross-cluster search. The moment two clusters’ data appear in one view, the app has become a fleet manager and has taken the Portal’s job, which §7 exists to prevent and which portal-architecture §8 prices as a paid, multi-cluster capability.
- Credential isolation is per connection, in separate keychain/keystore entries, with no shared refresh path.
Under those five terms the connection list is a client-side convenience and not a cross-cluster session, and §7’s actual concern is untouched. That is the argument; the owner has to accept or reject it, because it edits a ruled item.
2.2 Three clusters running nextcloud: and a gap in the label ruling
Section titled “2.2 Three clusters running nextcloud: and a gap in the label ruling”The owner is right that the disambiguator already exists. It is
../architecture/flows/launcher.md §13
Q5, overruled 2026-08-13:
Q5 OVERRULED 2026-08-13: every tile always shows its stack name, iPad-style. […] 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).
Launcher labels are stack names, not app names. That is what tells three
Frappe benches apart today, and it is what tells nextcloud from
nextcloud-staging apart on one cluster.
★ But it does not solve the cross-cluster case, and this is a real gap.
Launcher.md §16 fixes the grouping key as (tenant, environment, stack):
“one tile per stack name: group key (tenant, stack)”. There is no cluster
component in that key. Three clusters each running a stack named nextcloud
produce three labels reading exactly nextcloud, and the middle-ellipsis rule
cannot help because the strings are identical.
Recommendation (recommendation): the alias/shortcut label is
<stack> · <connection>, where <connection> is the user’s own name for
that cluster from §2.1’s address book, user-chosen, therefore short and
memorable, therefore ellipsis-friendly. The cluster qualifier is a client-side
concern and must not be pushed into the launcher payload, which is under a
hard 10,250-byte ceiling (launcher.md §13 Q7, ruled “No” on raising it a third
time) and which has no concept of a cluster anyway, being served by one.
3. Android launcher integration (ruled): and the verified mechanics
Section titled “3. Android launcher integration (ruled): and the verified mechanics”RULED: Android launcher integration on the console app, user-disableable globally and per-app.
The owner asked for the mechanics to be checked against current Android documentation rather than taken on faith. They check out, with one addition and one useful consequence he did not raise.
3.1 <activity-alias>: build-time declaration, runtime toggle, no prompt
Section titled “3.1 <activity-alias>: build-time declaration, runtime toggle, no prompt”Verified against the Android manifest reference. An <activity-alias> is
“an alias for an activity, named by the targetActivity attribute”; the
target “must be in the same application as the alias and declared before the
alias in the manifest”; the alias “presents the target activity as an
independent entity, and can have its own set of intent filters”, its own
android:icon and its own android:label. android:enabled “default value
is "true"”, so every alias must ship explicitly android:enabled="false"
or a fresh install carpets the drawer before the user has connected anything.
The runtime toggle is PackageManager.setComponentEnabledSetting(). Verified:
the CHANGE_COMPONENT_ENABLED_STATE permission “is not required if target
components are running under the same uid with the caller”; an app changing
its own components needs no permission, and the call shows the user nothing.
A signature permission is only required to touch another application’s
components.
This is the mechanism, and it is the whole reason the feature is possible: icons appear in the app drawer, on their own, with no prompt, when the user connects a cluster.
3.2 requestPinShortcut(): dynamic, home screen, and unavoidably prompted
Section titled “3.2 requestPinShortcut(): dynamic, home screen, and unavoidably prompted”Verified against the Android shortcuts guide, quoting it directly:
Note: When you attempt to pin a shortcut onto a supported launcher, the user receives a confirmation dialog asking their permission to pin the shortcut. If the user doesn’t let the shortcut be pinned, the launcher cancels the request.
and
Note: If the user doesn’t let the shortcut be pinned to the launcher, your app doesn’t receive a callback.
The dialog is a system dialog, it is per shortcut, and it cannot be
suppressed; the creation cannot happen in the background precisely because
it requires that confirmation. The old silent path, the
com.android.launcher.action.INSTALL_SHORTCUT broadcast, survives only inside
ShortcutManagerCompat as a fallback for API 25 and lower; on Android 8.0
(API 26) and above it is gone.
★ Say this plainly so nobody promises it in a demo or a roadmap:
Silent home-screen population is unavailable to anyone, on any Android version we would ship for. It is not an SHC limitation, a permissions gap, or something a launcher partnership unlocks. It is platform design.
What is silent is the app drawer, via aliases. What is prompted is the home screen, via pinned shortcuts. Those are different surfaces and users will conflate them; the UI copy must not.
3.3 The hybrid (recommendation)
Section titled “3.3 The hybrid (recommendation)”- Flagship apps →
<activity-alias>. Automatic, drawer, zero prompts, icons baked into the APK. The flagship set is bounded and stable (apps/flagship/), which is exactly the property build-time declaration requires. - The long tail →
ShortcutManager.requestPinShortcut(). Any app in the catalog, icon fetched from the catalog at runtime, arbitrary label and intent, lands on the home screen, one explicit tap each. Surfaced as a “Add to home screen” affordance next to each app in the console’s app list, so the prompt reads as a consequence of the user’s own tap rather than as an interruption.
3.4 The real costs: named, not glossed
Section titled “3.4 The real costs: named, not glossed”- Icons bake in at build time. An alias’s
android:iconis a drawable resource compiled into the APK. A catalog icon change requires an app release. ★ But this cost is much smaller here than it looks, because of a ruling already made. Launcher.md §13 Q4 ruled: “Category glyphs + monogram fallback. NO VENDOR LOGOS”, “a trademark question with an owner’s name on it, not a lane’s”, noting that 76 of 91 icons were third-party URLs across 57 origins. So the alias icon set is a bounded set of category glyphs plus generated monograms, not 91 churning vendor logos. Category glyphs change approximately never. The build-time bake is a real constraint and an almost-zero-frequency one. The pinned-shortcut path, which takes a runtime icon, absorbs whatever churn remains. - Manifest bloat. Each alias is a manifest entry and a compiled component. Past a few dozen the manifest, the APK and package-manager scan time all grow. Cap the alias set at the flagship list and hold the line; the pinned-shortcut path exists so the cap never becomes a product limit.
- OEM launcher jank.
setComponentEnabledSettingis well known to be unreliable on some OEM launchers: icons not appearing, disappearing, or not refreshing until the launcher is relaunched or the device rebooted. This is not fixable from inside the app. It needs (a) a device matrix in QA, and (b) UI copy that does not promise instant appearance, and (c) a visible “apps didn’t show up?” path in settings rather than a support ticket. - A disabled alias is still a shipped component. Users with a component inspector will see every flagship alias in the APK regardless of connection. That is an inventory disclosure of what SHC ships, not of what this customer runs, acceptable, but state it so it is not discovered later.
3.5 ★ It must reconcile, not just add
Section titled “3.5 ★ It must reconcile, not just add”The owner is right that this is the part that decides whether the feature is good or a liability.
Add-only is a defect, not a v1 simplification. When an app is uninstalled on the cluster, its alias must be turned off, or the user accumulates dead icons that launch into 404s, and a dead icon is worse than a missing one, because it teaches the user that the icons lie.
Design it as a reconcile loop against the deployment list, not as an event handler on install:
desired = { alias(stack) : stack ∈ deployments(active connection), entitled, user-enabled }actual = { alias : getComponentEnabledSetting(alias) == ENABLED }
for alias in desired - actual: setComponentEnabledSetting(alias, ENABLED, DONT_KILL_APP)for alias in actual - desired: setComponentEnabledSetting(alias, DISABLED, DONT_KILL_APP)Properties this shape buys that an event handler does not:
- Idempotent: running it twice changes nothing, so it is safe to run on every foreground, on connection switch, and on push.
- Convergent after missed events. The app will be backgrounded, killed, and offline. It will miss install and uninstall events. A reconcile loop does not care; a handler chain does.
- Correct on connection switch, which under §2.1 is the common case: the
previous cluster’s entire alias set lands in
actual - desiredand switches off in one pass, with no special-casing. - Correct on entitlement change, which matters because the launcher menu is a Hobby+ feature (see §10); the alias set is that entitlement rendered into the drawer, so a lapse must retract icons, and only a reconcile does that without a bespoke revocation path.
The one thing that needs no reconcile, exactly as the owner said: aliases
are package components, so uninstalling the SHC app removes every one of
them with the package. There is no orphan sweep, no cleanup broadcast, no
BOOT_COMPLETED receiver keeping a registry tidy. This is the strongest
argument for aliases over pinned shortcuts: pinned shortcuts are owned by
the launcher and outlive the app’s control, which is why the long tail should
stay a deliberate, per-app, user-initiated act rather than something the app
does in bulk on the user’s behalf.
Reconcile input (recommendation): the same inventory the launcher already computes, read through the daemon rather than re-derived. Do not invent a second source of truth for “what is deployed here”; launcher.md §16’s group key and environment-precedence rules are subtle, already ruled, and already tested, and a second implementation in Kotlin will drift.
User control, per the ruling: global off, and per-app off. Per-app off must
be sticky and must win over reconcile; it belongs in desired, not as a
post-filter, or the next reconcile pass silently re-enables what the user
turned off.
4. ★ The architectural ruling that matters most: the app is not its own browser
Section titled “4. ★ The architectural ruling that matters most: the app is not its own browser”RULED: Custom Tabs on Android, SFSafariViewController on iOS. Never an
embedded WebView for app content.
The owner asked for the SSO claim to be verified against the forward-auth implementation before asserting it. It verifies, and the real mechanism is different from, and stronger than, the summary.
4.1 The correction: the shared thing is not an SHC cookie
Section titled “4.1 The correction: the shared thing is not an SHC cookie”The summary was “a shared Keycloak SSO session enforced at Traefik
forward-auth”. The gate part is exactly right:
../architecture/access-control.md
“Forward-auth flow” §2–3: Traefik calls GET /api/auth/forward-auth with the
client’s Authorization header “or shc_access_token cookie”, and SHC
validates the bearer against the issuing realm’s userinfo endpoint.
But shc_access_token is not the thing that makes SSO work across apps.
From traefik/plugin/launcher.go, in the header comment that exists precisely
because this was got wrong once:
The identity gate that closed the disclosure proved callers from the
shc_access_tokencookie, which auth.go sets, host-only, and ONLY on the forward-auth leg. Every app carrying its own native SSO (gitlab, huly, affine, nextcloud) is deliberately UNGATED, so that cookie is never minted there and never travels between hosts.
and later:
shc_access_tokenis SameSite=Lax and host-scoped.
A parent-domain cookie was considered and refused for two recorded reasons:
it would create a new ambient credential on every host of the parent domain,
and it “STRUCTURALLY CANNOT COVER THE ESTATE” because bitspur routes
hq.flyingfoxlabs.in, outside .corp.bitspur.com.
So what actually provides single sign-on is the Keycloak SSO session cookie
at the auth host, KEYCLOAK_IDENTITY and AUTH_SESSION_ID, named in the
same file, which every app’s OIDC redirect rides silently, gated or ungated.
The owner’s conclusion survives this correction and gets stronger. A WebView has its own cookie jar. What that jar fails to contain is not an SHC cookie but the Keycloak session itself. Consequences:
- Every gated app launched in the WebView performs a full interactive Keycloak login, not a silent redirect.
- And so does every ungated app: gitlab, huly, affine, nextcloud all carry their own native SSO against the same Keycloak. An embedded WebView breaks the apps that are not behind the gate too. The summary understated the blast radius.
- An app-per-tab WebView architecture would make it worse than one login per app; it would be one login per app per app launch, since the jar is the shell’s and its lifetime is the shell’s.
That is the single-sign-on property the gate exists to provide, destroyed.
4.2 Custom Tabs: verified, and the platform-sanctioned OAuth surface
Section titled “4.2 Custom Tabs: verified, and the platform-sanctioned OAuth surface”Chrome’s Custom Tabs documentation, verbatim:
Shared cookie jar and permissions model so users don’t have to sign-in to sites they are already connected to, or re-grant permissions they have already granted.
and, on the alternative:
WebViews […] don’t share state with the browser and add maintenance overhead.
One Keycloak login covers every app opened. That is the property, stated by
the platform vendor, and it is the same property SFSafariViewController
provides on iOS.
They are also the only sanctioned OAuth surface. RFC 8252 (OAuth 2.0
for Native Apps) states native apps MUST NOT use embedded user-agents for
authorization requests, and that authorization endpoints MAY detect and
block them. Google does block them, returning disallowed_useragent. Since
traefik/plugin/launcher.go already implements PKCE (RFC 7636) with S256,
on both legs, unconditionally, an embedded WebView would break the login the
estate already ships; the launcher’s own PKCE tests
(launcher_pkce_test.go) exist because Keycloak refused every non-PKCE attempt
with invalid_request: Missing parameter: code_challenge_method.
★ The same family of reasoning has already been ruled twice, and the
precedent should be cited rather than re-argued.
../decisions/2026-08-16-marketplace-identity-and-install.md
§4 refuses an iframe of the store inside the console because “the iframe
cannot hold a session, not ‘degrades’, cannot”, and rejects the CHIPS /
Storage Access API workarounds because they put “a tracking-style consent
prompt” in front of the user. A WebView is that same defect with a native
wrapper: an isolated jar, an unusable session, and a workaround worse than
the disease. This ruling is the mobile edge of a boundary already drawn twice.
4.3 The consequence: what the native app is for
Section titled “4.3 The consequence: what the native app is for”Rendering is delegated. The native app does exactly five things and no sixth:
- Connection management (§2.1, the address book, one active at a time).
- The launcher grid: the console’s own UI, native, not a web page.
- Notifications.
- The alias reconcile loop (§3.5).
- NetBird handoff, not a VPN client (§6).
Everything else opens a Custom Tab.
This composes with the aliases exactly as the owner said, and the composition is the nicest property in the design: tapping a drawer icon fires an intent into the SHC app, which resolves the stack against the active connection and opens a Custom Tab straight to that host, already authenticated, because the tab shares the browser’s Keycloak session. The user experiences “a Nextcloud icon on my phone that just opens Nextcloud, logged in”, and the app never rendered a byte of Nextcloud.
4.4 ★ Two owed items this ruling creates, neither of them optional
Section titled “4.4 ★ Two owed items this ruling creates, neither of them optional”(a) The native app needs its own Keycloak client, and it must be public.
The launcher’s PKCE flow deliberately runs a confidential client
server-side inside the middleware, and deliberately refuses to hand a token to
JavaScript: “An estate access token in a variable readable by any script on
somebody else’s application is a worse credential than the one this feature was
trying to avoid needing”. A native app cannot reuse that flow: it holds no
secret, so it must be a public client with PKCE (the standard AppAuth
pattern, and what RFC 8252 prescribes). That is a new per-cluster Keycloak
client, and access-control.md’s redirect-URI discussion notes that
publicClient: true puts the client back under the strict redirect-URI rule
that shc-forward-auth’s confidential wildcard is exempted from. The native
client’s redirect URIs must be exact: the app’s custom scheme
(shc-console://, cf. scheme: "shc-console" already in app.config.js) or an
App Link / Universal Link, never a wildcard.
(b) Keycloak SSO cookies are non-persistent by default, and mobile will
expose that. launcher.go records the measurement:
Keycloak’s SSO cookies (
KEYCLOAK_IDENTITY,AUTH_SESSION_ID) are NON-PERSISTENT by default: the browser drops them when it exits.
On desktop that produces the already-documented “sign in while signed in” confusion after a browser restart. On mobile it is much worse, because Android and iOS kill the browser process routinely and without user action. The promise “one Keycloak login covers every app” is true within a browser session and false across restarts, and on a phone restarts are frequent and invisible.
This must be measured and decided before the launcher-icon feature ships, or the flagship experience is: tap a drawer icon, get a login screen, several times a day. The levers are the realm’s SSO Session Idle / Max settings and Keycloak’s “Remember Me” (which makes the identity cookie persistent). This is an estate-side fix, not an app-side one, which is worth noticing, because it means a PWA-first console hits the identical wall and gets the identical benefit. It is not a native-vs-PWA discriminator; it is a prerequisite for both.
5. iOS: no alias equivalent, ship anyway (ruled)
Section titled “5. iOS: no alias equivalent, ship anyway (ruled)”iOS has no <activity-alias> equivalent. There is no supported API by
which an app places additional, independently-labelled, independently-iconned
launchers for third-party destinations on the Home Screen.
setAlternateIconName swaps the app’s own icon and is one icon, not many.
The only per-app-icon story on iOS is: the user visits the app’s URL in Safari and does Share → Add to Home Screen, once per app, by hand.
★ And it is weaker still than “manual”, in a way worth stating. An Add-to-Home-Screen result is only a real web app, installed, standalone, push-capable, if the origin serves a web app manifest. Those origins are Nextcloud, GitLab, Immich, Huly. SHC does not control them. Whether a given app gets a proper icon and a standalone window or a generic screenshot bookmark is decided by third-party upstreams, per app, and will be inconsistent across a catalog of 91. SHC can improve this for apps it serves itself and cannot for the rest.
RECOMMEND SHIPPING iOS ANYWAY (recommendation). The management surface, notifications, connection management and the NetBird handoff are entirely platform-neutral, and they are, per §7, the substance of the product. Do not withhold a platform because one enhancement does not port. The reverse error is the common one: holding both platforms hostage to feature parity, and shipping neither.
The honest framing for users, which should appear in the product and not only here: the drawer-icon feature is an Android feature. Not “coming soon to iOS”.
6. Reachability: the owner’s correction, carried
Section titled “6. Reachability: the owner’s correction, carried”6.1 The problem is real
Section titled “6.1 The problem is real”../architecture/access-control.md, verbatim:
Exposure axis | Per-deployment and orthogonal to access:
exposure: lan(the default, reachable on the LAN only) orexposure: internet.
and:
Access and exposure are two independent axes.
Legacy public: migration seeds exposure to lan as well. So the default
SHC deployment is unreachable from a phone on cellular, and a mobile console
that can only work on the home Wi-Fi is not a mobile console.
6.2 The owner’s correction, verified: NetBird already solves it
Section titled “6.2 The owner’s correction, verified: NetBird already solves it”The owner corrected an earlier framing in which a bundled VPN profile was the reason to go native. He is right, and every part of it checks out:
- NetBird is a flagship app.
apps/flagship/netbird/app.yaml:name: netbird,version: "0.76",description: NetBird - VPN mesh networking with WireGuard,category: networking, tags includingvpn,mesh,wireguard,zero-trust. The package is complete:compose.yaml,backup.yaml,oidc.plug.yaml,postgres.plug.yaml, an init job, an exporter, a socket, and tests. - It is wired into the identity plane.
apps/standalone/identity-broker/netbird.plug.yamlexists, alongside the plugs for gitlab, immich, mailcow, matrix, midpoint, nextcloud and peertube. - NetBird ships first-party iOS and Android clients, from the App Store and Play Store.
Therefore: reachability is solved by an app the user installs from the store,
and SHC should not build or embed a VPN client. Not “should defer”,
should not. Shipping a WireGuard client would mean a NEPacketTunnelProvider
network extension on iOS and a VpnService on Android, a second key custody
problem, a second set of store review questions, and a permanent maintenance
obligation to duplicate a flagship app that is already packaged, already
brokered into Keycloak, and already has better clients than we would write.
One honesty note on the wiring, since the app doc says so itself:
netbird/app.yaml records that “NetBird has no CLI/API for bootstrapping a
PAT. The first admin must log into the dashboard UI (via Keycloak) and create a
PAT manually”. So first-run NetBird is not push-button today. That is a NetBird
packaging gap worth closing on its own merits; it is not a mobile gap and it
does not change this recommendation.
What the console app should do about VPN (recommendation): detect that the active connection is unreachable, and deep-link to NetBird (install it, or open it) with a plain explanation. A handoff, not a tunnel.
6.3 The operational wrinkle: one line, as asked
Section titled “6.3 The operational wrinkle: one line, as asked”iOS permits only one active VPN configuration at a time. Verified: only one
NEPacketTunnelProvider (enterprise VPN) may run on the system at once, and
where an enterprise VPN and a Personal VPN are both configured the enterprise
one takes route precedence. A user already on a corporate VPN will conflict
with NetBird. That is a NetBird and user-education matter. It is not a reason
to build anything, and specifically it is not an argument for embedding our
own client; an embedded client would hit the identical limit.
6.4 ★ Where this leaves the native case
Section titled “6.4 ★ Where this leaves the native case”With reachability carried by NetBird, and with web push working on iOS since
16.4 for Home-Screen-installed web apps (verified: Web Push on iOS is
available only to Home Screen web apps, an open Safari tab has no
PushManager, and requires a manifest plus a user-gesture permission request;
iOS 16 or newer is now the overwhelming majority of the installed base),
notifications are not a native-only need either.
The only remaining native-only capability is the Android <activity-alias>
launcher integration. One platform. An enhancement, not a foundation.
The owner asked that the proposal follow the argument rather than protect the earlier framing. It follows.
7. PWA-first: evaluated as the likely answer, and adopted (recommendation)
Section titled “7. PWA-first: evaluated as the likely answer, and adopted (recommendation)”7.1 The console is a strong PWA candidate
Section titled “7.1 The console is a strong PWA candidate”The reasons compound, and several are specific to this repo rather than general PWA advocacy:
- It is already served from the estate, on a domain the user trusts. Console-architecture §2 ruled “daemon-served, same-origin. shcd serves the built SPA on the estate’s existing publicUrl host: no extra containers, no CORS, ships atomically with releases”. A manifest and a service worker are additive bytes on a vehicle that is already ruled and already owed. The PWA is close to free.
- ★ The Keycloak session already lives there. This is the decisive one. §4’s entire problem, an isolated cookie jar, does not exist for a PWA, because there is no native shell to have a jar. An installed PWA on Android runs in the browser’s own storage; the Custom-Tab-vs-WebView question stops being a question because there is nothing to embed.
- Installable on both platforms, from Chrome and from Safari’s Add to Home Screen, with no store account, no review, no signing identity, no release channel.
- One codebase, and
apps/consoleis already a web build with routes and screens written. - It ships with the estate. Version skew between app and daemon, normally the hardest problem in a management client, disappears, because the console bytes and the daemon are one release. A store-distributed native app must support every daemon version its users are running, forever. This is a large, permanent, easily-underestimated cost that PWA-first simply does not incur.
What a PWA gives up:
- The alias icons. Fully. There is no web API that places drawer icons. This is the entire native-only surface, and it is real.
- Anything needing a background service the OS will not run. No periodic background reconcile, no long-lived socket. Partially mitigated: a service worker runs on push delivery, so a push-triggered reconcile is possible on Android, but nothing runs on a schedule, and iOS is stricter still.
- A wrinkle needing measurement before it is promised: on iOS, a Home Screen web app has its own storage container rather than sharing Safari’s, and links opened out of it land in Safari with a different session. So the iOS PWA console likely costs one Keycloak login at install and then persists, acceptable, and still one login rather than one per app, but the interaction between the installed console’s session and Safari’s session must be measured on a device, not assumed. Combined with §4.4(b)‘s non-persistent SSO cookie default, this is the top of the measurement list.
7.2 What still justifies a thin native Android app?
Section titled “7.2 What still justifies a thin native Android app?”The honest answer is: one thing, and it is not yet enough on its own.
- The
<activity-alias>drawer integration. That is the list.
And there is a verified argument against shipping a thin native shell to a store. App Store Review Guideline 4.2 (Minimum Functionality), verbatim:
Your app should include features, content, and UI that elevate it beyond a repackaged website. If your app is not particularly useful, unique, or “app-like,” it doesn’t belong on the App Store.
A native console whose substance is “open a Custom Tab at the estate’s console URL” is a repackaged website by construction. 4.2 is a far more likely rejection ground than 4.7 (§9), and it is one the architecture invites by design, since §4 rules that rendering is delegated. A native app only clears 4.2 once the alias reconcile, notifications, and connection management are real and visible, which is to say, the native app must earn its way past review by being the things a browser cannot do, and until it is, it should not be submitted.
★ And then the sharpest fact in the whole analysis:
The one native-only capability exists on the one platform that does not require a store.
Android permits sideloading, F-Droid, and self-hosted APKs. The estate can serve its own APK. So the alias feature can ship with zero store review, zero store presence, zero 4.2 exposure and zero IAP exposure to precisely the audience most likely to want it, who are by construction people who self-host their own infrastructure and are unbothered by “Install unknown apps”.
7.3 The recommendation
Section titled “7.3 The recommendation”- PWA-first for the console, both platforms. Manifest, service worker, install affordance, web push. Ships with the daemon per console-architecture §2. This is the product.
- An optional Android APK, distributed off-store from the estate (and
optionally F-Droid), for users who want drawer icons. It is the same
apps/consolecodebase through the native lane that already exists. It is an enhancement layer over the PWA, and it must not become a fork. - No iOS native app. Nothing yet justifies it, and this document declines to manufacture a justification. Revisit only if iOS ships an API that makes per-app icons possible, or if a capability appears that web push and NetBird do not cover.
- No Play Store or App Store presence for the console at v1. Revisit when there is a reason that is not “apps live in stores”.
8. The PWA story per surface
Section titled “8. The PWA story per surface”8.1 Console: yes
Section titled “8.1 Console: yes”Per §7. Gains: one codebase, no review, no store presence to maintain, ships with the estate, same-origin with the Keycloak session. Gives up: alias icons and OS-scheduled background work.
8.2 Portal: no. The owner guessed correctly, and here is the reason
Section titled “8.2 Portal: no. The owner guessed correctly, and here is the reason”Not a preference: the reasons the console’s case is strong are each absent for the portal:
| Console’s reason | Portal |
|---|---|
solves a reachability problem (exposure: lan) | none: my.selfhostedcloud.org is on the public internet, run by us, always reachable |
| ships with the estate, so no version skew | nothing to ship with: it is a Frappe bench we operate and deploy continuously |
| installability is genuinely useful | install prompts on an admin console are noise. People reach an admin console from a desktop browser with tabs and bookmarks |
| same-origin with a session that already exists | our own IdP on our own domain; a browser already handles this perfectly |
Its one native-shaped need is push for approval requests. That comes
straight out of the request-and-approve ruling,
../decisions/2026-08-16-portal-cluster-identity.md
§2:
RULED: request-and-approve is the default.
with §2.1 routing the request across two populations: a cluster tenant user requests, a portal account approves. An approval that waits is a purchase that does not happen, so notifying the approver promptly is a genuine product requirement rather than a nice-to-have.
Web push already covers it, on desktop unconditionally and on iOS since 16.4 for Home-Screen-installed web apps. And email covers the rest.
Conclusion, with the one nuance that keeps it honest (recommendation):
The portal is not a PWA product and should not be a mobile app. But it should ship a web app manifest and a service worker, purely so that an approver who wants push on an iPhone can install it and get push, since on iOS that is the only path to
PushManager.
Ship the capability; do not promote the install. No beforeinstallprompt
banner, no “get the app” interstitial, no store listing, no portal app. An
approver who wants a push-capable icon can add one; nobody is asked to.
8.3 ★ THE PLATFORM MATRIX (decided, 2026-08-16)
Section titled “8.3 ★ THE PLATFORM MATRIX (decided, 2026-08-16)”This is a capability matrix, and it is decided. It says what each target can reach, not what ships; shipping is §7.3 (a recommendation) and, for desktop, a release decision nobody has taken yet. Read a cell as “is this objective reachable on this platform at all”, because the whole reason to write it down is that two of the answers are platform floors that no amount of engineering moves.
| objective | Android native | iOS native | PWA | Desktop |
|---|---|---|---|---|
| management surface (stacks, health, events, install/deploy/restore) | yes | yes | yes | yes |
| notifications | yes | yes | yes (web push; iOS needs Home-Screen install) | yes |
| per-app icons | yes: drawer, silent | NO, hard platform limit | no | yes, and better, see below |
| home-screen / desktop placement | one confirmation tap each | manual, per app, by the user | manual | yes, fully dynamic, no dialog |
| auth without a platform-isolation spike | Custom Tabs (§4.2) | ASWebAuthenticationSession | n/a; the browser is the session (§7.1) | yes, no spike needed |
| store presence available | yes | yes | no | n/a |
| background re-warm | limited | very limited | no | yes |
Android native reaches every objective, with one asterisk that is a platform floor, not a gap:
- Aliases populate the DRAWER silently.
setComponentEnabledSetting()on the app’s own components needs no permission and shows the user nothing (§3.1). This is the mechanism the whole feature rests on. - The HOME SCREEN still needs one confirmation tap each.
requestPinShortcut()raises a system dialog, per shortcut, that cannot be suppressed, and the silentINSTALL_SHORTCUTbroadcast is gone on API 26 / Android 8 and above (§3.2). This is a platform floor since Android 8. It is not an SHC limitation, a permissions gap, or something a launcher partnership unlocks. Nobody may promise silent home-screen population in a demo or a roadmap.
iOS native reaches everything EXCEPT per-app icons, and that exception is
a hard platform limit with no API (§5). There is no <activity-alias>
equivalent; setAlternateIconName swaps the app’s own icon and is one icon,
not many. The only per-app story is the user doing Share → Add to Home Screen
by hand, whose quality is decided by third-party upstreams’ manifests,
Nextcloud’s, GitLab’s, Immich’s, which SHC does not control. Everything
else on the list ports: management surface, notifications, connection
management, the NetBird handoff.
PWA gets launcher + marketplace on both platforms, and the honest limits are three:
- Auth is plausible on Android and doubtful on iOS, pending the spike. On Android the installed PWA runs in the browser’s own storage, so §4’s cookie-jar problem does not exist. On iOS a Home Screen web app has its own storage container rather than sharing Safari’s, and links opened out of it land in Safari with a different session. This must be measured on a device, not assumed (§7.1, owed work item 6).
- No store presence. By construction, which §7.3 counts as a feature.
- No background re-warm. Nothing runs on a schedule; a service worker runs on push delivery, and iOS is stricter still.
★ DESKTOP reaches everything, and does two things BETTER than Android. This is the part of the matrix that was not obvious and is the reason it is worth writing down:
.desktopfiles and Start Menu shortcuts are fully dynamic. There is no build-time set, no manifest to declare aliases in, no APK to rebuild when the catalog changes, and no confirmation dialog. Writing a.desktopfile into~/.local/share/applications/or a shortcut into the Start Menu is a file write. So the constraint that shapes the entire Android design, §3.4’s “icons bake in at build time; a catalog icon change requires an app release”, and the cap on the alias set, simply does not exist on desktop, and neither does §3.2’s per-icon prompt. Desktop gets the silent drawer and the dynamic long tail, which is strictly more than Android manages.- The embedded-webview auth story needs no platform-isolation spike at all. §4.4(a)/(b) and owed work items 5 and 6 exist because mobile makes session sharing between a native shell and the system browser hard. A desktop shell embeds a webview it controls, on a machine whose browser profile the user already owns; there is no App-Bound-Domains equivalent and no Custom-Tabs-vs-WebView question to lose.
★ And desktop is a RELEASE decision, not a build decision: the lanes
already exist. §0.1 found them in-tree today: Tauri (src-tauri/,
tauri:build) and GNOME (vite.config.gnome.ts, gjs), both under apps/console, both
CI-typechecked, all sitting under console-architecture §8’s “web is the only
released target”. So the question for desktop is the same one §0.2 poses for
mobile, promotion from insurance to product, and the marginal cost is
lower than mobile’s, because desktop needs neither of the two spikes mobile
needs.
macOS is the awkward case. The .desktop-file property above is Linux;
Windows Start Menu shortcuts are the close equivalent. macOS has no clean
dynamic equivalent for per-app icons: the Dock and Launchpad are populated
from .app bundles, so a per-app icon means generating bundles, which brings
code-signing, notarization and Gatekeeper into a feature that is a file write
everywhere else. Treat macOS as reaching everything except the per-app
icon story, alongside iOS, and do not let it hold the Linux and Windows lanes
hostage; that is the §5 error repeated one platform over.
The two rows to quote when someone asks why the feature is uneven: silent home-screen population is impossible on every platform we would ship for except desktop; per-app icons are impossible on iOS and macOS and cheap everywhere else. Both are platform design.
9. App Store posture: argued, not asserted
Section titled “9. App Store posture: argued, not asserted”Recorded because the owner raised it. Every guideline below was read from the current App Review Guidelines rather than recalled, and one of the owner’s premises needs correcting.
9.1 Guideline 4.7: ★ the premise needs correcting, the conclusion survives
Section titled “9.1 Guideline 4.7: ★ the premise needs correcting, the conclusion survives”The owner referred to 4.7 as the “your own app store” rule. Today’s 4.7 is titled “Mini apps, Mini Games, Streaming Games, Chatbots, Plug-ins, and Game Emulators”, and it is a permissive section, not a prohibition:
Apps may offer certain software that is not embedded in the binary, specifically HTML5 and JavaScript mini apps and mini games, streaming games, chatbots, and plug-ins. […] You are responsible for all such software offered in your app, including ensuring that such software complies with these Guidelines and all applicable laws.
The argument that it does not apply, which is stronger than the owner’s version because the section is about a different thing entirely:
- 4.7 governs software offered in your app: code that executes on the iOS device, inside the app’s process or its embedded runtime. That is why 4.7.2 forbids extending native platform APIs and 4.7.3 governs sharing privacy permissions: the mini app is running on the phone.
- An SHC install puts a container on the customer’s own server. Nothing is downloaded to the device, nothing executes on the device, no runtime is embedded, no native API is exposed to third-party code. The device’s role is to send an authenticated instruction to a remote machine the customer owns.
- The category is remote-infrastructure management, and it ships on the App Store today at scale: AWS Console, DigitalOcean, Linode, Portainer, Cloudflare. Each lists, provisions and configures third-party software on remote servers. None is treated as an app store.
- The console app’s install action is strictly less than those: under
../decisions/2026-08-16-marketplace-identity-and-install.md§5 the store itself is reached by top-level navigation tomarketplace.selfhostedcloud.org, not embedded, so the catalog browsing and purchasing surface is a website in a browser, not a surface in the app.
Assessment: 4.7 most likely does not apply. Not certain, no guideline read is, but the argument is on the merits and the precedent class is large.
★ RECORDED AS DECIDED: the “your own app store” framing is STALE and must not be repeated. Not in a plan, not in review notes, not in a conversation with a reviewer. Today’s 4.7 is titled “Mini apps, Mini Games, Streaming Games, Chatbots, Plug-ins, and Game Emulators” and it governs code executing ON THE DEVICE, which is why 4.7.2 forbids extending native platform APIs and 4.7.3 governs sharing privacy permissions. An SHC install puts a container on the customer’s own server; nothing is downloaded to the device, nothing executes on it, no runtime is embedded. Repeating the stale framing does active harm in two directions: it invites a reviewer to evaluate the app against a section that does not fit, and it makes us design defensively against a rule that is not the one we have to clear. The rule we have to clear is 4.2; see §9.6.
9.2 Guideline 4.8: Sign in with Apple. Not triggered, and the exception is explicit
Section titled “9.2 Guideline 4.8: Sign in with Apple. Not triggered, and the exception is explicit”4.8 attaches to apps that “use a third-party or social login service (such as Facebook Login, Google Sign-In, Log in with X, Sign In with LinkedIn, Login with Amazon, or WeChat Login) to set up or authenticate the user’s primary account”. Its listed exceptions include, verbatim:
- App exclusively uses company’s own account systems
- App is education/enterprise requiring institutional account
Both apply. The portal app authenticates against our own IdP, the first exception, precisely. The console app authenticates against the customer’s own Keycloak, in their tenant realm, the second exception, precisely: an institutional account issued by the customer’s own identity system.
It would become mandatory if “Sign in with Google” (or any social IdP) is ever offered as a primary login on either app. Note this is not about a customer configuring Google as a federated IdP inside their own Keycloak; that is their realm configuration, invisible to us and to Apple; it is about our app offering a social login button.
9.3 ★ Guideline 3.1.1: the real commercial risk, and the structural dodge
Section titled “9.3 ★ Guideline 3.1.1: the real commercial risk, and the structural dodge”Not 4.7. IAP. Verbatim:
If you want to unlock features or functionality within your app […] you must use in-app purchase. Apps may not use their own mechanisms to unlock content or functionality, such as license keys, augmented reality markers, QR codes, cryptocurrencies and cryptocurrency wallets, etc.
The “license keys” clause is the one to notice, because SHC’s entitlement spine
is Keygen licences
(../decisions/2026-08-16-marketplace-entitlement-and-licensing.md:
“ERPNext invoice → broker POST /record → Keygen record”). If the app ever
took a licence key and unlocked in-app functionality with it, 3.1.1 would bite
directly and by name.
The already-ruled purchase design dodges it structurally. Under portal-cluster-identity §2, purchasing authority is request-and-approve: a request is raised, an approver acts in the portal, and per §4.3 the approver acts in the portal “on a portal object”, which is why purchase approval survives an L2 seal at all. Combined with marketplace-identity §5’s new-tab signed handoff to the store, the result is:
- Purchases happen on the web, in the portal, through SHC’s own processor (ERPNext Sales Invoice as source of truth; Keygen as entitlement store; processors pluggable underneath; portal-architecture §7 names Hyperswitch as “the likely orchestrator”, which is directional, not ruled, and should not be written down as settled).
- The app requests and installs what is already entitled. It shows entitlements; it does not sell them.
- Money never touches the app.
★ Record this as what it is: a consequence, not a workaround. The request-and-approve ruling was made for governance reasons, “turns approval into a real decision instead of a rubber stamp”, months of App Store compliance later than it should be relevant. The IAP-safe posture is what that ruling produces on its own. A design that is compliant by accident of good architecture is far more durable than one engineered around a rule, because there is no in-app purchase flow to re-litigate when the rule moves.
9.4 Why “the apps sell nothing” is defensible, not merely convenient
Section titled “9.4 Why “the apps sell nothing” is defensible, not merely convenient”RECOMMENDED POSTURE: the apps sell nothing. No prices, no purchase UI, no upgrade button, no “unlock” affordance, no plan comparison.
The argument, in the terms that actually decide it:
Apple requires IAP for digital content and functionality consumed in the app. It does not require IAP for goods and services consumed outside it. An SHC subscription is consumed on infrastructure the customer owns and operates: a Nextcloud running on their hardware, a Keycloak realm holding their users, a Traefik gate enforcing their access policy. The phone is a management client for a service that exists whether or not the phone does. The app is not the product; the estate is.
The precedent is unambiguous and large. AWS, DigitalOcean, Linode, Cloudflare, Salesforce and Shopify all ship management apps for services with substantial recurring fees. None sells its service through IAP. This is not a grey area being probed; it is the settled shape of an entire app category.
An additional structural fact that strengthens it here: the SHC console app often manages an estate the app cannot reach without NetBird (§6) and which continues to operate, bill, serve users and run backups when the phone is switched off. The service’s independence from the app is not an argument; it is an operational property.
9.5 ★ Anti-steering is moving: do not write down numbers
Section titled “9.5 ★ Anti-steering is moving: do not write down numbers”Rules on linking out to external purchase have changed materially and repeatedly (the Epic injunction, the 2025 US ruling, the EU DMA regime) and now differ by jurisdiction within the same guideline. This is directly visible in the current text, which carves the US storefront out by name:
These entitlements are not required for developers to include buttons, external links, or other calls to action in their United States storefront apps.
In all other storefronts, except for the United States storefront, where this prohibition does not apply, apps and their metadata may not include buttons, external links, or other calls to action that direct customers to purchasing mechanisms other than in-app purchase.
Therefore:
- Do not state commission percentages or link-out permissions as settled fact anywhere: not in this doc, not in a plan, not in marketing.
- The shape is: US storefront currently permissive on link-outs; other storefronts restrictive with entitlement carve-outs; EU governed separately under the DMA.
- Re-check at build time, from the primary source, per storefront. Treat today’s reading as perishable.
- ★ And notice why the posture was chosen: “the apps sell nothing” does not depend on how this area settles. An app with no purchase UI and no external purchase links is unaffected by every one of these movements in either direction. That robustness is a feature of the choice, and it is worth more than the marginal conversion a link-out would buy.
9.6 ★ THE APP REVIEW STRATEGY (decided, 2026-08-16): what we submit, and the gate that sinks submissions
Section titled “9.6 ★ THE APP REVIEW STRATEGY (decided, 2026-08-16): what we submit, and the gate that sinks submissions”This governs if and when a native app is submitted. It does not overturn §7.3, which recommends PWA-first with no store presence at v1; it says that should a submission happen, this is the posture, and it changes what the build has to contain, so it is not deferrable to submission day.
9.6.1 Submit an ESTATE MONITORING AND OPERATIONS CLIENT that also launches apps, not a launcher
Section titled “9.6.1 Submit an ESTATE MONITORING AND OPERATIONS CLIENT that also launches apps, not a launcher”The framing is the strategy. A “launcher” is, in App Review’s vocabulary, a thing that opens other things, which is a bookmark folder with an icon, and 4.2 Minimum Functionality exists to reject exactly that:
Your app should include features, content, and UI that elevate it beyond a repackaged website. If your app is not particularly useful, unique, or “app-like,” it doesn’t belong on the App Store.
★ 4.2 is the real risk, not 4.7 (§9.1), not 4.8 (§9.2), and not 3.1.1, which the purchase design already dodges structurally (§9.3). §7.2 already named it: a native shell whose substance is “open a Custom Tab at the estate’s console URL” is a repackaged website by construction.
★ And here is the counterintuitive consequence that must not be got backwards: THINNESS is what trips 4.2, so STRIPPING FEATURES TO REDUCE REVIEW SURFACE MAKES REJECTION MORE LIKELY, NOT LESS. The instinct to submit a minimal build “to get through review” is precisely inverted. There is no minimum-surface strategy for 4.2; there is only a substance strategy. The app must earn its way past review by being the things a browser cannot do.
9.6.2 The native capabilities that carry it, most legible to a reviewer first
Section titled “9.6.2 The native capabilities that carry it, most legible to a reviewer first”Ordered by how immediately a reviewer sees native capability, not by build cost. A reviewer spends minutes, and the first three do the work:
- Live Activities on long installs and backups. A Dynamic Island / Lock Screen surface updating during a multi-minute operation is unmistakably native, is impossible on the web, and maps onto a real thing the product does; installs and backups genuinely take minutes.
- Home Screen widgets for estate health. Visible without opening the app; no web equivalent exists on iOS.
- Local Network discovery. Finding an estate on the LAN is real utility
given
exposure: lanis the default (§6.1), and its permission prompt is itself proof of native capability: a web page cannot ask for it, so the reviewer sees the system dialog and the question of “is this a website” is answered by the OS. - Actionable push: approve/deny a purchase request, acknowledge an alert, from the notification.
- Face ID / Touch ID and Keychain for connection credentials.
- App Intents: Siri and Shortcuts integration for common operations.
- A Files provider extension, surfacing estate storage in the Files app.
Each is a genuine capability, not a compliance ornament, which is what makes the list defensible: a design that is compliant by accident of good architecture is far more durable than one engineered around a rule (§9.3).
9.6.3 ★ THE PRACTICAL GATE THAT SINKS SUBMISSIONS: a WORKING DEMO ACCOUNT
Section titled “9.6.3 ★ THE PRACTICAL GATE THAT SINKS SUBMISSIONS: a WORKING DEMO ACCOUNT”Record this as OWED BUILD WORK, not as a policy note. It is the most common cause of rejection for apps in this category, it has nothing to do with guideline interpretation, and it cannot be produced in the hour before submission.
App Review needs credentials that work. A reviewer in a different country, on an unknown network, with no estate of their own, must be able to sign in and see the app do something. An SHC console app with no cluster to connect to is a login screen, which is a 4.2 rejection and a “we could not review your app” rejection at once.
What is owed, concretely:
- A real, seeded, publicly reachable demo cluster. Not a mock, not a screenshot mode, not a fixture bundle: a live estate with stacks installed, health history, events, an app list and a backup or two, so the reviewer sees a populated product rather than an empty one.
- Publicly reachable, which for this product is the hard part: the default
is
exposure: lan(§6.1), and the NetBird handoff (§6.2) is not something a reviewer will do. The demo cluster must be reachable without a VPN, which makes it a deliberately-exposed estate and therefore its own small security design: a scoped tenant, throttled, nothing real behind it, rotated credentials. - Credentials in the review notes, in the App Store Connect demo-account fields, and kept working across every resubmission. A demo account that has expired between builds is a rejection.
- A reviewer path that does not require Local Network permission, since a reviewer on cellular cannot use it; the capability is a strength (§9.6.2), but it must not be the only way in.
This is build work with an owner and a schedule, and it belongs in §11.
10. ★ The tier tension: the owner’s premise does not match the repo. NEEDS OWNER RULING
Section titled “10. ★ The tier tension: the owner’s premise does not match the repo. NEEDS OWNER RULING”10.0 ★★ A RULING WAS MADE ON A WRONG PREMISE, AND IT NEEDS RE-DECIDING: OWNER INPUT NEEDED
Section titled “10.0 ★★ A RULING WAS MADE ON A WRONG PREMISE, AND IT NEEDS RE-DECIDING: OWNER INPUT NEEDED”Read this before anything else in §10, and do not implement past it.
Later on 2026-08-16 the owner ruled that the console is gated to Hobby. That ruling is not recorded here as settled, and this document deliberately does not resolve it, because the premise he was given was wrong.
What he was told: that the console and the marketplace were “born paid”, features added alongside the free tier rather than carved out of it, so gating the console to Hobby was a clean addition that took nothing away.
That was wrong for the console. It may hold for the marketplace; it does not hold for the console, and §10.2 below is the evidence, read out of the tree:
TIERS.md’s free tier includes “the full single-node experience”, alongside “full app catalog + install / deploy / update / restore / recover” and “the full CLI is visible”. The console is not named as an exclusion anywhere inTIERS.md; it is not mentioned inTIERS.mdat all.2026-08-14-console-architecture.md§3 says the opposite of born-paid, explicitly: “Every realm user may sign in; operator screens gate on the RBAC role matrix.”TIERS.md’s Hobby section names what paid adds, and it is three things: named environments, the support bundle, the MCP server, under the sentence “Those three are the whole of what every paid tier adds over free.” The console is not among them.
Therefore moving the console to Hobby TAKES SOMETHING AWAY FROM FREE. It is a carve-out, not an addition. The owner decided it believing it was additive. That is a different decision from the one he made.
★ What has changed since, and what has not. TIERS.md dropped the
no-rug placement promise earlier the same day (dd35fac98, “drop the
no-rug promise, keep the placement heuristic”); the section now reads “This
section describes how we currently place features. It is not a commitment
about future placement, and it is deliberately not written as one.” So
nothing forbids the carve-out any more; the objection that this document
originally raised (§10.2’s closing paragraph, now amended) is gone. The
objection that remains is narrower and harder: the decision was made on a
false description of what it cost. Removing a prohibition does not convert a
carve-out into an addition.
(Note for whoever touches TIERS.md next, not this lane’s to fix: the
Environments section still says moving the line “after someone depends on it
is exactly the rug-pull the promise above forbids”, a dangling reference
to the promise that was deleted above it.)
10.0.1 ★ THE ALTERNATIVE THAT NEEDS NO CARVE-OUT: it may already be his intent
Section titled “10.0.1 ★ THE ALTERNATIVE THAT NEEDS NO CARVE-OUT: it may already be his intent”Before re-deciding, notice that the outcome he wants may already exist.
What is already gated Hobby-and-up, ruled and written down, is the
launcher menu and app-SSO: 2026-08-14-console-architecture.md §3:
Free tier (permanent): no launcher menu and no SSO into apps. The traefik launcher/menu overlay and app-SSO are paid (Hobby+) features.
And that is precisely the feature the mobile app exists to deliver. §10.3 works it through: the Android drawer aliases are the launcher menu rendered into another surface, and app-SSO is what makes tapping one land you logged in rather than at a login form. The one native-only capability in the entire proposal (§6.4) is therefore already behind Hobby without a single new ruling.
So there are two shapes, and only the owner can say which he meant:
| “console gated to Hobby" | "console free, launcher paid” | |
|---|---|---|
| what free loses | the whole management surface: stacks, health, events, app list, install/deploy/restore | nothing it has today |
relationship to TIERS.md | a carve-out requiring an edit to the declared free tier | already consistent; no edit |
| relationship to console-architecture §3 | contradicts “every realm user may sign in” | already what §3 says |
| new rulings needed | yes: TIERS.md and console-architecture §3 both change | none |
| App Store 4.2 exposure (§10.3) | a free download that does nothing = an empty paywall | app is free and useful; the icons are the paid part |
| paid feature the mobile app delivers | console access | drawer icons + app-SSO, the thing the app is for |
If “console free, launcher paid” is what he meant, it is already satisfied
and there is nothing to do. If he means the console itself, that is a
TIERS.md edit and a console-architecture §3 edit, and it should be made on
the corrected premise, knowingly, as a carve-out, rather than inherited from
a briefing error.
This is flagged, not resolved. §12 Q5 carries it as the open question.
The rest of §10 is the original tension, retained, and it is the evidence §10.0 rests on. The owner raised this as a real review risk, and he is right that the risk shape matters. But the premise is contradicted by two documents, and correcting it makes the problem smaller and sharper rather than bigger.
10.1 What the owner said
Section titled “10.1 What the owner said”The console is a Hobby (paid) feature and free tier does not get it. So a free-tier user who downloads the console app can do nothing.
10.2 What the repo says
Section titled “10.2 What the repo says”TIERS.md, free tier: it is a long list, and it includes:
- Full app catalog + install / deploy / update / restore / recover.
- The full CLI is visible; paid commands tell you what tier unlocks them.
- The CLI, health, and the full single-node experience.
TIERS.md, Hobby tier, and this sentence is decisive:
Those three are the whole of what every paid tier adds over free; Pro and Enterprise carry all of them too, unchanged.
The three are: named environments, the support bundle, and the MCP
server. The console is not among them, and is not mentioned in TIERS.md
at all.
Console-architecture §3 goes the other way explicitly:
Auth: per-estate confidential Keycloak client, role-gated screens. Every realm user may sign in; operator screens gate on the RBAC role matrix.
And its entitlement section names what is paid, precisely, and it is not the console:
Free tier (permanent): no launcher menu and no SSO into apps. The traefik launcher/menu overlay and app-SSO are paid (Hobby+) features.
So: the launcher menu and app-SSO are Hobby+. The console is not.
★ AMENDED: the promise that was in the way has been removed. This
paragraph originally read: “There is also a promise in the way. TIERS.md
records that the free tier was declared ‘before the first sale, deliberately’,
with a no-rug commitment … exactly the move that section exists to prevent.”
That is no longer true. TIERS.md dropped the no-rug placement promise
on 2026-08-16 (dd35fac98), and now says placement “is not a commitment about
future placement, and it is deliberately not written as one”. The
no-rug/no-brick language that survives is about the licensing runtime,
soft-degrade, nothing stops, no data lost, and TIERS.md marks it “not to be
confused” with feature placement.
So nothing prohibits moving the console behind Hobby. What remains is not a
prohibition but a fact about cost: it is still a carve-out from the declared
free tier, not an addition to it, because TIERS.md’s free tier says “the
full single-node experience” and console-architecture §3 says “every realm
user may sign in”. §10.0 is where that lands.
10.3 Why the corrected line is better for the App Store problem too
Section titled “10.3 Why the corrected line is better for the App Store problem too”The minimum-functionality risk the owner feared largely evaporates, and what remains lands in a cleaner place:
- A free-tier user’s console works. Stacks, health, events, the app list, install/deploy/update/restore. That is substantial, functional, and free, so there is no empty paywall to reject under 4.2, and the app’s content problem (§7.2) is about native substance, not entitlement.
- What free tier lacks is exactly the launcher menu and app-SSO, which is exactly the Android alias feature. The drawer icons are the launcher menu rendered into another surface, and app-SSO is what makes tapping one land you logged in. So the alias feature is correctly Hobby+ with no new ruling at all, and its entitlement gate is already written down.
- Which means the tier story reads cleanly to a reviewer and to a user: the app is free and useful; the icons are the paid part. That is a normal, defensible freemium shape, and it is what the existing rulings already produce.
10.4 Recommendation
Section titled “10.4 Recommendation”Do not move the console to Hobby. Keep TIERS.md’s free tier as declared;
keep console-architecture §3’s “every realm user may sign in”; gate the
launcher menu, app-SSO, and therefore the Android drawer icons at Hobby+, which
is already ruled.
Recorded as an owner question (§12 Q5) because the owner stated the
opposite, and because if he intends to move the console behind Hobby that is a
change to TIERS.md and to console-architecture §3, not a mobile
decision.
★ AMENDED: status upgraded, recommendation unchanged. This is no longer
a recommendation against a hypothetical: the owner has since ruled that the
console is gated to Hobby, on the premise that it was “born paid” and
therefore additive. §10.0 records why that premise is wrong and why the
ruling needs re-deciding. This section’s recommendation stands as written, and
it is now the alternative to a live ruling rather than advice on an open
question. The clause about “the no-rug promise” above is stale; TIERS.md
dropped it the same day (§10.2). Nothing forbids the carve-out; it is simply
still a carve-out.
11. Owed work
Section titled “11. Owed work”- Kill or claim the marketplace native lane.
apps/marketplace/app.config.jsdeclares iOS and Android with template residue identifiers (com.marketplace.app) that console-architecture §1 already ruled must never ship. Delete the lane (recommended) or rebrand it. Not both, not neither. - PWA on the console: web app manifest, service worker, install affordance, web push. Rides console-architecture §2’s daemon-served SPA (owed work item 2 there), which is the prerequisite; today nothing serves console bytes on any estate, confirmed: no Go code embeds or serves the console SPA.
- PWA capability on the portal: manifest + service worker + web push for approval requests. No install promotion. (§8.2)
- Native public Keycloak client for the console app: PKCE, exact redirect
URIs on the
shc-console://scheme or an App Link, never a wildcard; distinct from the launcher’s confidential client. (§4.4a) - Measure and fix Keycloak SSO session persistence for mobile browsers:
KEYCLOAK_IDENTITY/AUTH_SESSION_IDnon-persistence, SSO Session Idle/Max, Remember Me. Blocks the drawer-icon feature from feeling like SSO, and benefits the PWA identically. (§4.4b) - Measure the iOS Home Screen web app session boundary: whether the installed console shares Safari’s Keycloak session, and what happens to links opened out of it. (§7.1)
- Alias reconcile loop (Android APK lane): desired/actual set difference
against the deployment list, idempotent, run on foreground / connection
switch / push; per-app user opt-out inside
desired, not after it. (§3.5) - Cluster qualifier on launcher labels for the multi-connection case: client-side only, not in the launcher payload (10,250-byte ceiling, ruled). (§2.2)
- NetBird handoff: unreachability detection on a connection, deep-link to install/open NetBird. No VPN client, no network extension. (§6.2)
- Android OEM device matrix for
setComponentEnabledSettingrefresh behaviour, plus non-promising UI copy and a self-serve recovery path. (§3.4.3) - Off-store Android distribution: signing identity, APK hosting from the estate, update channel, optional F-Droid. (§7.3)
- ★ A REAL, SEEDED, PUBLICLY REACHABLE DEMO CLUSTER: a live estate with stacks, health history, events and backups, reachable without a VPN (so: a deliberately-exposed, scoped, throttled tenant with rotated credentials), plus the credentials in App Store Connect’s demo-account fields and kept working across resubmissions. This is build work, not a policy note, and it gates any store submission on either platform. (§9.6.3)
- The 4.2 substance set, if a store submission is ever intended: Live Activities on long installs/backups, Home Screen health widgets, Local Network discovery, actionable push, Face ID/Keychain, App Intents, a Files provider extension. Named as owed because stripping features to reduce review surface makes rejection more likely, not less (§9.6.1), so this is an entry condition rather than a follow-up. (§9.6.2)
- A desktop release decision: the Tauri, GNOME and VS Code lanes exist
and are CI-typechecked today (§0.1). Desktop reaches every objective in
the matrix and needs neither of the two spikes mobile needs (owed
items 5 and 6), because
.desktopfiles and Start Menu shortcuts are fully dynamic with no build-time set and no confirmation dialog, and an embedded webview on the user’s own machine has no platform-isolation problem. macOS is the exception on per-app icons. Promotion, not construction. (§8.3)
12. Open owner questions: unresolved
Section titled “12. Open owner questions: unresolved”Q1: Build stack: native, cross-platform, or PWA-first?
This document recommends PWA-first for both platforms, plus an optional
off-store Android APK from the existing apps/console native lane (§7.3).
That is a recommendation and not a ruling. Note the premise correction in §0:
the cross-platform lane already exists and is CI-typechecked, so the real
question is promotion, not selection.
Q2: Does the console app ship before the portal app? Unresolved. The repo makes the console strictly cheaper: it has native lanes, routes and screens today; the portal is a Frappe bench with nothing (§1.3). But console-architecture §8 says “revisit promotion after the Portal ships”, i.e. the standing ruling sequences it the other way. These two facts point in opposite directions and only the owner can break the tie. If §8’s ordering stands, note it does not block the PWA console, which is a web change and sits inside owed work item 2.
Q3: Who maintains two app-store presences? Unresolved, and this document’s answer to Q1 is partly an attempt to make the question unnecessary: PWA-first plus off-store Android requires zero store presences. If the owner wants store distribution anyway, the standing cost is two developer accounts, two review queues, two signing-identity custody problems, expedited-review capability for security fixes, and a permanent obligation to support every daemon version in the field, for a two-person team. Name the owner before committing, not after the first rejection.
Q4: ★ Does the native console get a connection list, overriding console-architecture §7? §7 rules “strictly single-cluster, in both web and native… no connection switcher anywhere in the console”. Today’s ruling requires the opposite. §2.1 proposes a narrowing (web unchanged; native gets an address book; one active connection; no aggregate views ever). This edits a ruled item and needs an explicit yes or no.
Q5: ★★ Is the console a Hobby feature?, RE-OPENED. OWNER INPUT NEEDED.
The owner has since RULED yes, but on a premise that was wrong. He was
told the console was “born paid” and that gating it to Hobby was therefore
a clean addition. It is not: TIERS.md’s free tier says “the full single-node
experience” and console-architecture §3 says “every realm user may sign in”,
so moving the console to Hobby takes something away from free. The no-rug
placement promise was dropped from TIERS.md the same day
(dd35fac98), so nothing forbids the carve-out, but it is still a
carve-out, and the decision was made believing it was additive.
★ And the alternative may already be his intent, satisfied, with no carve-out at all: what is already gated Hobby-and-up is the launcher menu and app-SSO (console-architecture §3), precisely the feature the mobile app exists to deliver, since the drawer aliases are the launcher menu in another surface and app-SSO is what makes tapping one land you logged in. So “console free, launcher paid” needs no new ruling, keeps free tier as declared, and gives a cleaner 4.2 story (the app is free and useful; the icons are the paid part).
Do not implement either shape until the owner re-decides on the corrected premise. Full statement of both options: §10.0 and §10.0.1.
Q6: Is the marketplace a third native surface?
apps/marketplace/app.config.js declares iOS and Android with template
identifiers nobody has ruled on. Recommendation: delete the lane (§1.3).
Q7: When may an Android APK be submitted to Play, if ever? Not at v1 under §7.3. If the answer is “never”, say so, because it removes a whole class of future compliance work, and if it is “eventually”, the 4.2 minimum-functionality bar (§7.2) sets the entry condition: the alias reconcile, notifications and connection management must be real first. ★ Amended: §9.6 now states the entry conditions in full: the substance set (§9.6.2) and the working demo cluster (§9.6.3, owed work 12), which is build work with a lead time and cannot be produced at submission.
Q8: Does the daemon expose an inventory endpoint the reconcile loop can
read, or does the app re-derive (tenant, environment, stack) grouping and
environment precedence itself? Recommendation: expose it. A second
implementation of launcher.md §16 in Kotlin will drift from the ruled one.
13. ★ MEASURED VERDICT: “log in once, tap anything” (spike, 2026-08-16)
Section titled “13. ★ MEASURED VERDICT: “log in once, tap anything” (spike, 2026-08-16)”Run as a throwaway spike against (a) the live bitspur estate and (b) a
local throwaway Keycloak brought up from the estate’s own pinned image,
registry.gitlab.com/bitspur/selfhosted-cloud/shc/keycloak@sha256:2c8c0a92bba9a5ecdb7581b7a8e87c867b51a4c22e509f2a002687c0f9195cf9.
No product code was written and no estate was changed.
13.0 The verdict in three lines
Section titled “13.0 The verdict in three lines”- The cross-origin half works, and it is not close. One sign-in, then a
second gated host on a different origin, a third on a different
registrable domain, an ungated app with its own Keycloak client, and
the native app’s own public client all completed silently: no
prompt, no consent screen, a
codeon the first redirect. §13.2. - The persistence half is broken by default, exactly as
launcher.gopredicted, and now measured end to end.KEYCLOAK_IDENTITYships with noMax-Ageand noExpires. Kill the browser process and the next gated host prompts. §13.3. - Of the two candidate fixes, only one exists. Persistent SSO cookie
lifetimes (Remember Me + the Remember-Me lifespans) is measured working.
“The app silently re-establishes the browser session from its own refresh
token” is not implementable against stock Keycloak; there is no endpoint
that trades a token for a browser SSO cookie, and
prompt=nonewith every hint attached still returnslogin_required. §13.4.
So the product premise survives, conditionally. “Log in once, tap anything, you are in” is true within one cookie jar, and it is a one-line realm setting away from being true across app restarts. It is false the moment the app opens URLs in a jar other than the one it signed in to, which is the one thing this lane could not measure. §13.5.
13.1 The question decomposes into two independent halves
Section titled “13.1 The question decomposes into two independent halves”This is the most useful thing the spike produced, because it says which half is an SHC question and which half is a platform question:
| Question | Owner | Status | |
|---|---|---|---|
| (a) Server | Given a Keycloak SSO session in the jar, does Keycloak mint a code for a second, different-origin relying party with no prompt? | SHC / Keycloak config | SETTLED: YES. §13.2 |
| (b) Client | Does the platform’s browser surface put both opens in the same jar? | iOS / Android platform | UNMEASURED. §13.5 |
A cookie jar is not an analogy for a browser here; for this question it is the browser. Two URLs opened against one jar are two URLs opened in one browser; two jars are two browsers. So (a) is fully measurable off-device, and it was.
13.2 Half (a): SETTLED. Cross-origin silent SSO works
Section titled “13.2 Half (a): SETTLED. Cross-origin silent SSO works”On the live estate, agents.corp.bitspur.com 302s to
auth.corp.bitspur.com/realms/corp/protocol/openid-connect/auth?client_id=shc-forward-auth&code_challenge=…&code_challenge_method=S256,
and the same URL with prompt=none and no cookies returns, verbatim:
HTTP/2 302location: https://agents.corp.bitspur.com/api/auth/oidc/callback?error=login_required&state=…So the silent leg exists and answers correctly for an unknown caller.
On the throwaway rig, one interactive sign-in at host A, then: same jar, no further credentials:
| # | What was opened | Result |
|---|---|---|
| M1 | first gated host, cold jar | PROMPTED (baseline) |
| M2 | interactive sign-in at host A | 302 + code minted |
| M3 | second gated host, different origin, same shc-forward-auth client | SILENT |
| M4 | ungated app with its own client (gitlab shape), different registrable domain | SILENT |
| M5 | native app, publicClient: true, exact redirect shc-console://auth/callback | SILENT |
| M6 | prompt=none silent check (the launcher’s hidden leg) | SILENT |
M4 matters more than M3: the estate’s gated hosts share one shc-forward-auth
client, so M3 alone could have been client-level session reuse. M4 is a
different client on a different registrable domain and it is still silent,
which is the property §4.1 claims for the ungated apps (gitlab, huly, affine,
nextcloud) and it is now measured rather than argued.
M5 validates §4.4(a) mechanically: a public client with an exact custom-scheme redirect URI completes the code flow in the shared jar and inherits the same session. The native client does not need, and does not get, a wildcard.
Control (two jars): a second, never-signed-in jar asking for the same
already-authorised host gets PROMPTED, and prompt=none gets
login_required. That is the WebView outcome §4 rules against, reproduced.
13.3 Half (b), second half of the brief: SETTLED, and it is worse than one prompt
Section titled “13.3 Half (b), second half of the brief: SETTLED, and it is worse than one prompt”The raw Set-Cookie headers Keycloak emits on a successful login, captured
verbatim from the rig:
--- rememberMe NOT ticked ---KEYCLOAK_IDENTITY Version=1;Path=/…/realms/corp/;HttpOnly;SameSite=LaxKEYCLOAK_SESSION Version=1;Path=/…/realms/corp/;Max-Age=36000;SameSite=Lax
--- rememberMe ticked ---KEYCLOAK_IDENTITY Version=1;Path=/…/realms/corp/;Max-Age=2592000;HttpOnly;SameSite=LaxKEYCLOAK_SESSION Version=1;Path=/…/realms/corp/;Max-Age=2592000;SameSite=LaxKEYCLOAK_REMEMBER_ME Version=1;Path=/…/realms/corp/;Max-Age=31536000;HttpOnly;SameSite=LaxKEYCLOAK_IDENTITY, the credential, carries no Max-Age and no
Expires unless Remember Me is ticked. It is a session cookie. Modelling a
browser process death as “drop every cookie with no expiry, keep the rest”:
| After the browser process dies | Remember Me OFF | Remember Me ON |
|---|---|---|
| cookies surviving | KEYCLOAK_SESSION, KC_AUTH_SESSION_HASH | KEYCLOAK_IDENTITY, KEYCLOAK_SESSION, KEYCLOAK_REMEMBER_ME, KC_AUTH_SESSION_HASH |
| open a gated host | PROMPTED | SILENT |
prompt=none | LOGIN_REQUIRED | SILENT |
Three findings inside that table are worth pulling out because each one is a trap:
KEYCLOAK_SESSIONsurvives the restart and is not a credential. It is persistent (Max-Age=36000) and the request still prompts. Anything that probes for “is there a Keycloak cookie?” to decide whether to show a sign-in affordance will read this cookie and be wrong. Only theprompt=noneleg answers the question, which is exactly whatlauncher.goalready does.KEYCLOAK_REMEMBER_MEalone does not revive anything. Measured directly: keepKEYCLOAK_REMEMBER_ME(365 days) andKEYCLOAK_SESSION, dropKEYCLOAK_IDENTITY; the next gated host isPROMPTEDandprompt=noneisLOGIN_REQUIRED. It pre-fills a username; it does not authenticate.- Remember Me is a checkbox the user must tick, and it is not pre-ticked.
Measured on the live estate login page:
rememberMeis enabled on thecorprealm (the checkbox renders, so the realm flag is on) and the input carries nocheckedattribute. So the estate today is in the worst configuration available: the lever exists, and nobody pulls it.
On the live estate, AUTH_SESSION_ID and KC_RESTART were also confirmed
non-persistent (Secure;HttpOnly;SameSite=None, no Max-Age), and
KC_AUTH_SESSION_HASH carries Max-Age=60.
13.4 The two fixes, evaluated
Section titled “13.4 The two fixes, evaluated”Fix A: persistent SSO cookie lifetimes in Keycloak. RECOMMENDED.
Section titled “Fix A: persistent SSO cookie lifetimes in Keycloak. RECOMMENDED.”Measured, with the realm’s Remember-Me lifespans as the only variable:
ssoSessionIdleTimeoutRememberMe / …MaxLifespanRememberMe | KEYCLOAK_IDENTITY persists | gated host after restart |
|---|---|---|
0 / 0 (inherit the non-remember values) | 0.42 days (10 h) | SILENT |
2592000 / 2592000 | 30.00 days | SILENT |
Note the first row: turning Remember Me on is necessary but not sufficient.
With the Remember-Me lifespans left at 0 the persistent cookie still expires
at ssoSessionMaxLifespan, 10 hours by default. “Log in once” then means “log
in once a day”. The lifespans have to be raised too, and they are the knob that
actually sets the promise.
Costs, stated honestly:
- A 30-day persistent identity cookie on a phone is a 30-day bearer credential in the browser’s cookie store, replayable by anyone holding the device unlocked. It is the same trade every consumer app makes, and it is a real widening of the window in which a lost phone is an authenticated phone.
- It is estate configuration, per realm, so it is a knob every operator has to be told about, and a default SHC has to choose. It is not an app change, which means (as §4.4(b) already says) a PWA gets the identical benefit for free. This is not a native-vs-PWA discriminator.
- It needs a user-visible sign-out that actually ends the session (Keycloak
end_session_endpoint), or a shared or family device keeps someone signed in for a month. - Remember Me being an unticked checkbox is the remaining gap. The realm flag is on today and does nothing until a human ticks it. Either the login theme pre-ticks it, or the promise stays a coin flip per login.
Fix B: the app re-establishes the browser session from its own refresh token. DOES NOT EXIST.
Section titled “Fix B: the app re-establishes the browser session from its own refresh token. DOES NOT EXIST.”Measured, and it fails at the first step:
app completes its own public-client code flow in the shared browser -> SILENTbrowser process dies -> surviving cookies: KC_AUTH_SESSION_HASH, KEYCLOAK_SESSIONapp reopens with prompt=none -> LOGIN_REQUIREDapp reopens with prompt=none + login_hint -> LOGIN_REQUIREDStock Keycloak exposes no endpoint that trades a refresh token, offline or
otherwise, for a browser SSO cookie. A refresh token buys the app its own
access token, in the app’s own memory, where the browser cannot see it. The
browser session and the app session are two sessions; the app holding one says
nothing about the other. This is the same wall launcher.go already documents
from the other side.
What the app can do, and it is worth naming so it is not mistaken for Fix B:
on launch, run its own authorization request in the shared browser surface
without prompt=none. If the Keycloak session is alive that is silent
(measured, M5); if it is dead the user gets one login screen, at launch,
where a login screen is expected, instead of a login screen at 3pm when they
tap the Nextcloud icon. That relocates the prompt, it does not remove it,
and it is worth doing in addition to Fix A, not instead of it.
Recommendation: ship Fix A, plus the launch-time re-auth as belt and braces. Do not put Fix B on a roadmap; it is not a thing.
13.5 ★ The four cells: UNMEASURED. Said plainly, as instructed.
Section titled “13.5 ★ The four cells: UNMEASURED. Said plainly, as instructed.”| native shell | home-screen PWA | |
|---|---|---|
| iOS | UNMEASURED | UNMEASURED |
| Android | UNMEASURED | UNMEASURED |
Why, exactly:
mobile_list_available_devicesreturns{"devices":[]}: no simulator, emulator or physical device is attached to this machine, and the box is headlesslinux/amd64with noadb, noxcrun, noemulatoronPATH.- The remote cloud device fleet is present but not authenticated
(
failed to get token from keyring), and reserving from it is a shared, billed resource this lane has no consent to spend. It was not allocated. - Independently: the estate cannot host the two-host test today either.
A sweep of all 35
*.corp.bitspur.comhosts in Certificate Transparency, with an iOS SafariUser-AgentandAccept: text/html, found exactly ONE live forward-auth-gated host:agents.corp.bitspur.com.pickeranswers401anddevices404;dtrack,messenger,openhandsandprojecttime out. The prior lane’s “three gated hosts” does not hold as of 2026-08-16 05:55 UTC. A second gated host has to be stood up before the on-device test is even runnable. - And there are no credentials for the
corprealm in this environment; the cachedshc-clioffline token is dead (invalid_grant: Offline user session not found).
A guess here would be worse than a gap, so there is no guess. What follows is the test to run, not a prediction of its result.
The exact procedure, per cell. Two gated hosts on different subdomains are
needed; agents.corp.bitspur.com plus one more (§13.5 above; one must be
stood up).
- Cold start: wipe the app and the browser’s site data.
- Open host A from the app. Sign in interactively. Tick Remember Me.
- Open host B from the app, the same way the product would. Record: prompt or no prompt.
- Force-quit the app and the browser process (Android:
adb shell am force-stopon both; iOS: swipe both from the app switcher). - Reopen host B from the app. Record: prompt or no prompt.
- Repeat 1–5 with Remember Me unticked; that is the default and therefore the real-world case.
The single highest-value thing that procedure will catch, and the reason
step 3 must not be skipped as “obviously fine”: on iOS the app has two
browser surfaces with different jars, and the natural implementation puts
the login in one and the app-opens in the other. ASWebAuthenticationSession
shares Safari’s cookie store, which is why it shows a consent alert.
SFSafariViewController has had a per-app data store, isolated from Safari,
since iOS 11. Sign in with ASWebAuthenticationSession, then open apps with
SFSafariViewController, and the session lands in a jar the app never reads
from; every tap prompts, and the product premise fails on iOS while passing
on Android. The two-jar control in §13.2 is exactly what that failure looks
like. Whether those two surfaces are one jar or two is the thing to measure
first, before any other cell.
A home-screen PWA is a third container again (§7.1 already flags this), so the iOS PWA cell is not implied by either native result and has to be run on its own.
13.6 What this means for the product decision
Section titled “13.6 What this means for the product decision”- The value proposition is real and the mechanism is sound. Nothing in the estate’s design stands in the way of “sign in once, tap anything”. §13.2 is as strong a result as this question can have off-device.
- It is gated on one realm setting, not on a build. Remember Me plus raised Remember-Me lifespans, pre-ticked. Until that lands, the honest promise is “sign in once per browser session”, and mobile browser sessions are short and end without the user noticing.
- None of this argues for native over PWA. Every result above is a property of the cookie jar and the realm, both of which a PWA has too. §7’s PWA-first recommendation is untouched by this spike, and §4.4(b)‘s “prerequisite for both, discriminator for neither” is confirmed.
- The one thing that could still kill the premise is a client-side jar split and it is an iOS implementation choice, not a platform verdict. §13.5.
Bindings honoured
Section titled “Bindings honoured”- Identity split:
../decisions/2026-08-16-portal-cluster-identity.md§1.5, §2, §4.1, §4.3: the L2 seal, request-and-approve, and what survives a seal. §1.2 adds the console app to the survives-L2 list. - Install and store boundary:
../decisions/2026-08-16-marketplace-identity-and-install.md§4 (no iframe, the cookie-jar precedent §4.2 extends to WebViews) and §5 (the new-tab signed handoff, which keeps the storefront out of the app). - Entitlement spine:
../decisions/2026-08-16-marketplace-entitlement-and-licensing.md: ERPNext invoice → broker → Keygen. §9.3 keeps all of it off the device. - Console surface:
2026-08-14-console-architecture.md§1 (identifiers), §2 (daemon-served SPA, the PWA vehicle), §3 (every realm user may sign in), §7 (contradicted: Q4), §8 (native lanes are insurance, the premise §0 corrects), and the free-tier entitlement lines (§10). - Portal surface:
2026-08-14-portal-architecture.md§7 (ERPNext/Keygen, Hyperswitch likely), §8 (multi-cluster is paid and portal-only), §9 (the portal is Frappe, §1.3, §8.2). - Launcher:
../architecture/flows/launcher.md§13 Q4 (category glyphs, no vendor logos, §3.4.1), Q5-overruled (stack-name labels, §2.2), Q7 (the 10,250-byte ceiling), §16 (group key, no cluster component, §2.2). - Access model:
../architecture/access-control.md(forward-auth flow;exposure: landefault, orthogonal to access) andtraefik/plugin/launcher.go(host-onlyshc_access_token, the Keycloak SSO session, PKCE S256, non-persistent SSO cookies), §4, §6.1. - Tiers:
../../TIERS.md: the declared free tier and the three Hobby additions (§10).