Console settings: the build order (design)
Status: open design. The console’s Settings screen names eight tenant-configuration surfaces and builds none of them (
features/console/src/SettingsScreen.tsx:145). This document ranks them into a build order and grounds that ranking in a token-scope check rather than in the op counts alone. Everything below is measured against the tree atorigin/main(970bec767, 2026-08-20) and againstdocs/reference/api/openapi.jsonatinfo.versionv0.0.61-0.20260820210521-6baaf384a7a3.
The headline correction. The starting premise for this lane was “all eight have daemon verbs, so the only question is whether a console session’s token carries the scopes.” Both halves of that need adjusting:
- The spec’s scope annotations understate the real gating.
securityis derived by probingRequirePermissionsmiddleware off the live chi chain (scripts/gen-openapi.go:207,walkScopes), and the generator’s own comment says an empty set is “an OPEN read, not an unknown one”. That is true of the router, and false of the product:/api/user/*and/api/method/shc.license.*carry no router gate and are nevertheless authorized, in the service layer and in the handler respectively. Reading-as “callable by anyone” would be wrong in both directions. - The console already answers the scope question for itself, and has since
before this lane:
GET /api/method/shc.console.gate(packages/apps-menu/src/daemon/useConsoleGate.ts). It is built, exported and unused by any settings surface.
1. What a Settings-eligible caller already holds
Section titled “1. What a Settings-eligible caller already holds”The floor for the Settings app is not read; it is manage:
// modules/console/access.go:120func SettingsPermitted(id user.Identity, tenant string) bool { return EstateVerb(id, tenant) >= user.VerbManage}with the gap to the console’s own read floor (OpsPermitted,
access.go:105) called out there as “the entire point: a read-only support
identity gets the console and does NOT get the settings app.”
So anyone who can open the screen these panels live on already clears
tenant:manage. Two consequences fall straight out of Service.Authorise
(ce modules/auth/service.go:1074):
- Every
tenant:*andstack:*scope is satisfied.tenant:managecarries the R-1 tenant blanket (“tenant:Vgrants V on every stack in the realm” (cemodules/user/service.go:97)) sostack:read,stack:operate,stack:manage,tenant:readandtenant:manageare all reachable by a caller who got this far. platform:manageis NOT satisfied. It is resource-independent and undeniable, andAuthorisegrants it only toIsPlatformAdmin(service.go:1171-1172), which isplatform:managein the parsed roles (modules/user/service.go:79), implicitly true for any master-realm identity (applyMasterRealmPrivilege,modules/auth/service.go:474) or the UDS local user, and otherwise an explicit grant. The comment there records what this cost to learn: the platform gates were enforcing tenant-tier for a period, and “that made every platform-tier gate in the product a tenant-tier gate.”
Therefore the scope verdict for any panel reduces to one question: does it
need platform:manage? A tenant admin driving the console has everything
else already.
2. Per-bucket scope verdict
Section titled “2. Per-bucket scope verdict”Counts are operations in openapi.json; platform:manage is the only scope
that can refuse a Settings-eligible caller.
| Surface | ops | GET / mutating | scopes present | verdict |
|---|---|---|---|---|
| People (users) | 12 | 5 / 7 | none at router | CALLABLE: authz is service-layer tenant:manage; one licence refusal on grant |
| Tenants | 4 | 2 / 2 | 2× platform:manage | READ CALLABLE, writes platform-only |
| Identity & SSO | 4 | 3 / 1 | none | CALLABLE (reads): 3 are self-authenticating; the 4th is a live probe |
| Domains & certificates | 13 | 7 / 6 | 6× platform:manage | READ CALLABLE, every write platform-only |
| Provider connections | 45 | 13 / 32 | 19× platform:manage, 2× tenant:manage, 2× tenant:read | MIXED: vault/provider reachable, storage writes platform-only |
| Environment precedence | 6 | 2 / 4 | 2× platform:manage, 1× stack:manage | READ CALLABLE, config.set/unset platform-only |
| Backup policy | 49 | 13 / 36 | 12× stack:manage, 11× tenant:manage, 10× stack:operate, 9× stack:read, 7× platform:manage | LARGELY CALLABLE: only the 7 key/mount routes refuse |
| Licence & entitlements | 7 | 1 / 6 | none at router | PLATFORM-ONLY IN FACT, see below |
The two rows where the spec is wrong, and why
Section titled “The two rows where the spec is wrong, and why”People. modules/user/router.go:106-120 mounts twelve routes with no
RequirePermissions. Authorization is inside the service: every mutating
entry point runs ResolveTargetTenant, which refuses a caller lacking
tenant:manage with X403930USRPRM and refuses a cross-tenant target with
X403931USRXTN (ce modules/user/service.go:377-397). That floor is exactly
SettingsPermitted’s, so a People screen is callable, with one caveat the
console already documents: POST /api/user/grant additionally passes the CE
role gate (modules/user/role_gate.go), which refuses organizational RBAC
with X403988RBCEEO on an unlicensed build. Revoke is never gated, by
doctrine: “taking access away must always work, whatever the license says”.
Licence. modules/license/router.go mounts seven routes with no scope
annotation, and gates them in each handler:
// modules/license/router.go:67if u := auth.UserFromContext(r.Context()); u != nil && !u.IsPlatformAdmin() { api.WriteError(w, auth.X403904NOTENT("(license)"))The router comment states the rule the spec cannot see: “status is readable by any platform admin; activate/activate_online/delink … are platform-admin only.” So the Licence panel is the one surface on the list a tenant admin cannot use at all, despite reading as unscoped.
Honest limits of this analysis
Section titled “Honest limits of this analysis”-in the spec means no router gate, not no authorization. Two of the eight buckets are gated invisibly (above); the remaining-rows have not each been traced to a service-layer check. Any panel built on a-route must treat the daemon’s refusal as the authority and must not infer permission from the spec.- Needs a live probe, cannot be answered statically: what
GET /api/method/shc.console.gateactually returns for a real Keycloak-authenticated console session on a live estate, specifically whether a tenant-realm console user resolvesverb: "manage"andsettings: true, and whether any real operator identity is a master-realm identity (and therefore silently platform-admin).applyMasterRealmPrivilegecarries its own warning: “SHC must NOT hand-add non-admin users to the master realm: every human/service account in master is, by construction, platform admin.” The backup gate asymmetry is a known daemon defect: CORRECTED 2026-08-23. This bullet was already wrong when it was written. It repeated a claim fromuseConsoleGate.tsthat ce had closed two days earlier, inaf0502a4(2026-08-18), and the stale text was later cited as corroboration for a fresh P0 report of the same closed hole.shc.backup.createisstack:operate;shc.backup.restoreandDELETE /api/resource/Backup/{id}arestack:manage; the vault value reads andshc.vault.exportaretenant:manage(ce18abd9b9). Verified on the bitspur estate against daemon0.0.62-SNAPSHOT-b02728a26/ ce181d69fd6062: a corp-realm identity holding exactlytenant:readis refusedX403900NOPERMon every one of those verbs, and the same identity raised totenant:manageis served. Pinned intests/_ce/modules/backup/router_permission_gate_test.go,router_tenant_read_refusal_test.goandtests/_ce/modules/vault/router_permission_gate_test.go. The build-order advice that followed it still holds on its own merits: policy before actions is the right order for Backup, but not for this reason.
3. What the console already establishes
Section titled “3. What the console already establishes”Screens shipping today (features/console/src, routes in apps/console/routes):
SpringboardScreen (/), EventsScreen (/events), MarketplaceScreen
(/marketplace), SettingsScreen (/settings), StackDetailScreen
(/stacks/...), plus the stack overlay’s tabs (features/console/src/stack/).
Every route the console calls today, measured:
/api/conditions /api/method/shc.events.stream/api/avatar /api/method/shc.stack.update/api/method/shc.user.avatar /api/resource/Backup/api/user/list /api/resource/JobRun/{id}/api/user/revoke /api/resource/HostMapping/… /api/resource/PortMapping/…The patterns a new panel inherits, with their reference implementations:
- Read:
useDaemonHttp(path, fetcher)from@package/apps-menu, returning{ data, error, isLoading, url, refresh }; unwrap the daemon’s{message}/{data}envelope at the hook, keep the model a pure function (conditions/useConditions.ts). - Poll, don’t stream, for state that must not silently go stale: the ruling is in that file’s header: “the failure mode of a broken stream is SILENCE, and silence renders as green.”
- Write:
getDaemonHttp+useDaemonBaseURL, behind aConfirmDialog, withdescribeErrorsurfacing the coded refusal verbatim (stack/PermissionsTab.tsx). - Tier awareness:
useConsoleGate()/canManage()/verbAtLeast(), with the doctrine attached: a hidden control “is the console declining to OFFER an action the caller would be refused at. It is not the refusal itself.” - Layout:
PageHeader/PageSection/Paragraphfrom@multiplatform.one/components;SettingRowinSettingsScreen.tsx:34is the label/value row. - Auth-off:
AuthDisabledNoticefor the estate that runs without Keycloak. - Placeholder:
stack/shared.tsx:36(“Not wired yet”), for a panel deliberately named rather than mocked.
And People is half-built already. PermissionsTab reads
GET /api/user/list and writes POST /api/user/revoke, tenant-scoped, with
its own header stating exactly why grant is unwired: “granting needs a
role-builder (user × scope × verb) plus the CE role_gate’s licensing
refusals … a real form rather than a confirm.”
4. The build order
Section titled “4. The build order”Ranked by operator value over cost, with the scope verdict as a hard input: a panel whose verbs a tenant admin cannot call is worth less than its op count suggests, and a read-only panel is far cheaper and safer than a mutating one.
1st: People (build this first)
Section titled “1st: People (build this first)”- Shows: the tenant’s users, their roles as scope/verb badges, and who
holds what. Estate-wide version of
PermissionsTab, minus the “this stack” highlighting. - Calls:
UserList(GET /api/user/list),UserRevoke(POST /api/user/revoke), both already wired and shipping; thenUserGrant,UserCreate,UserDelete,UserResetPassword. - Read-only? No, but revoke-first: the existing tab already proves the read + one safe write.
- Scope risk: none for read/revoke. Grant meets
X403988RBCEEOon an unlicensed build, which is a feature for this panel: it is the first place the console will surface a licence refusal as product copy. - Size: medium. The role-builder (user × scope × verb) is the real work and is the reusable piece; Tenants and Backup policy both want a scope-shaped control after it.
- Depends on: nothing.
- Why first: the highest-value thing an operator opens Settings to do is answer “who can reach my estate”; the daemon surface is callable by exactly the identity that can open the screen; the component pattern already exists and ships; and it is the only panel whose first increment is moving existing code up a level rather than writing a new integration.
2nd: Licence & entitlements (read-only)
Section titled “2nd: Licence & entitlements (read-only)”- Shows: tier, expiry, entitlement list, grace/degradation state; the trial verb where the estate qualifies.
- Calls:
LicenseStatus(GET /api/method/shc.license.status) for the panel;LicenseTrial,LicenseActivate,LicenseRefreshonly behind platform-admin. - Read-only? Yes as proposed, one GET.
- Scope risk: high and structural. Every route is platform-admin at the handler. A tenant admin must see a stated refusal, not an empty panel.
- Size: small.
- Depends on: nothing, but wants the refusal-rendering convention that People’s grant path establishes.
- Why second: one call, high operator value, and it forces the console to learn how to say “you are not platform admin”, a lesson four other panels need.
3rd: Environment precedence (read-only first)
Section titled “3rd: Environment precedence (read-only first)”- Shows: effective config per key with the scope that won (global / tenant / deployment), which is the axis the estate has already been bitten by.
- Calls:
ConfigList,ConfigGet(bothPOST, unscoped at router);StackConfigNoref. Writes (ConfigSet/ConfigUnset) areplatform:manageand stay behind the gate. - Read-only? Yes in v1.
- Scope risk: low for read; writes platform-only.
- Size: small–medium; the precedence rendering is the design work.
- Depends on: nothing.
- Why third: cheap, and it is the panel that makes an invisible failure class visible; a config row that silently falls back to a default is precisely what a precedence view exposes.
4th: Domains & certificates (read-only)
Section titled “4th: Domains & certificates (read-only)”- Shows: the estate’s DNS records with their heritage/ownership, and the cert inventory with issuer and expiry.
- Calls:
DnsRecords,DnsRecord(GET),DnsValidate,CertList,CertEdge,CertDelivery,ClusterCertsList. All seven reads are unscoped; all six writes areplatform:manage. - Read-only? Yes, and it should stay that way.
DnsTakeover,DnsReap,CertsRotateare estate-shaped destructive verbs that want a CLI’s deliberation, not a button. - Scope risk: none for the read set.
- Size: medium, two tables and an expiry model.
- Depends on: nothing.
5th: Tenants
Section titled “5th: Tenants”- Shows: the tenant list with per-tenant quota/state; create and delete behind platform-admin.
- Calls:
TenantList,TenantGet(unscoped);TenantCreate,TenantDelete(platform:manage). - Read-only? Read-first.
- Scope risk: every mutation is platform-only, and delete is the single most destructive control in this whole document; it must be gated, confirmed by typing the tenant name, and honest that the daemon is the authority.
- Size: small for read; the write half is small code and large consequence.
- Depends on: People (the same role-builder shape), and the refusal-rendering convention from Licence.
6th: Backup policy (the schedule/retention half only)
Section titled “6th: Backup policy (the schedule/retention half only)”- Shows: per-stack schedule and retention policy, and the last-backup state; not the restore/browse machinery.
- Calls:
BackupScheduleList,BackupScheduleGet,BackupRetentionGet,BackupRetentionPreview(stack:read);BackupScheduleSet/Unset(stack:operate),BackupRetentionSet/Reset(stack:manage), all satisfied bytenant:manage. - Read-only? Policy read first; policy write second.
- Scope risk: low on paper, but this bucket carries the known daemon defect above. Nothing here should present as an authorization boundary until ce mounts the gates.
- Size: large (49 ops); the proposal deliberately takes ~8 of them.
- Depends on: stack selection, which
StackDetailScreenalready has; the estate-wide policy view is the new part. - Why not higher: the stack overlay already carries a Backups tab, so the marginal value of an estate-wide view is lower than every panel above it.
7th: Provider connections (read-only inventory)
Section titled “7th: Provider connections (read-only inventory)”- Shows: configured providers and grants, storage backends and their
health, vault status.
ProviderList,ProviderShow,ProviderGrants,StorageLs,StorageVolumeLs,NfsStatus,CephfsStatus,VaultStatus, reads only. - Read-only? Yes, emphatically. Nineteen of its 45 ops are
platform:manageand includevolume.rebind,restore-snapshot,volume.rmandassert-lease-lost, verbs whose blast radius does not belong behind a click in v1. - Scope risk: mixed; the read set is clear.
- Size: large surface, medium if scoped to inventory.
- Depends on: nothing, but is the least urgent read.
8th: Identity & SSO (defer)
Section titled “8th: Identity & SSO (defer)”- Shows: the realm the estate authenticates against and the discovery document it resolved.
- Calls:
AuthOidcRealm,AuthOidcRealmForHost,AuthOidcDiscovery: three self-authenticating reads. The fourth route in the bucket,SystemKeycloakResetAdminPassword, is a break-glass verb and does not belong on this screen at all. - Read-only? Yes.
- Scope risk: none.
- Size: small.
- Why last: the three reads are diagnostics the Settings header already half-answers (it names the daemon), and everything an operator actually wants here (federation, IdP config, redirect URIs) has no daemon surface yet. Building the panel now would name a surface without filling it, which is the failure this screen’s placeholder was written to avoid.
5. What this changes on the Settings screen itself
Section titled “5. What this changes on the Settings screen itself”The panel copy currently gates on the wrong thing: it says each surface ships
“as its daemon verbs are confirmed reachable”, which reads as though the daemon
were the blocker. It is not: 139 operations across 125 routes exist, and the
console is served by the daemon (modules/console/serve.go), so the origin is
the daemon’s own. The owed work is the screens. A sibling change is correcting
that copy; this document is the order they get built in.
6. Open questions
Section titled “6. Open questions”- Does a real tenant-realm console session resolve
verb: "manage"/settings: truefromshc.console.gate? Needs a live estate probe. - Are any real operator identities master-realm (and therefore silently platform-admin)? Governs whether the platform-only panels are usable in practice or refuse for everyone who opens them.
- Should the platform-only panels (Licence, Tenants’ writes, Domains’ writes) render a refusal, or be absent for a non-platform caller? The console gate doctrine argues for shown and refused on informational surfaces and absent on action controls, but it has not been ruled.
- The backup router gate defect is ce work with a console consequence; does it get fixed before the Backup panel ships, or does the panel ship with a note that the boundary is cosmetic?
Appendix: one claim in this lane’s notes, REFUTED on review (2026-08-20)
Section titled “Appendix: one claim in this lane’s notes, REFUTED on review (2026-08-20)”The drafting pass carried a parting note that shc.backup.create,
shc.backup.restore and DELETE /api/resource/Backup/{id} mount without
RequirePermissions, making any console gate on them cosmetic. That is
false and is recorded here so it cannot be repeated. Read at
ce/modules/backup/router.go: the router binds three wrappers:
manage = stack:manage, operate = stack:operate, read =
stack:read, and every verb named in the claim is wrapped:
r.With(operate).Post("/api/method/shc.backup.create", …)r.With(manage).Post("/api/method/shc.backup.restore", …)r.With(manage).Post("/api/method/shc.backup.restore_from_file", …)r.With(manage).Post("/api/method/shc.backup.recover", …)The cited source file (useConsoleGate.ts) does not exist in the tree
under that name, and no cosmetic comment of that shape survives in
features/console. A UI gate on the backup verbs is therefore backed by
a real daemon refusal, and no authorization gap exists here. The general
lesson stands and is why this appendix exists: the generated API
description’s blank scope column means no router-level gate, never no
authorization: service-layer and handler-level gates (ResolveTargetTenant
for /api/user/*, IsPlatformAdmin for shc.license.*) are invisible to
it, and a scope audit that reads only the spec will both over- and
under-report.