Skip to content
SHC Docs

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 at origin/main (970bec767, 2026-08-20) and against docs/reference/api/openapi.json at info.version v0.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:

  1. The spec’s scope annotations understate the real gating. security is derived by probing RequirePermissions middleware 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.
  2. 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:120
func 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:* and stack:* scope is satisfied. tenant:manage carries the R-1 tenant blanket (“tenant:V grants V on every stack in the realm” (ce modules/user/service.go:97)) so stack:read, stack:operate, stack:manage, tenant:read and tenant:manage are all reachable by a caller who got this far.
  • platform:manage is NOT satisfied. It is resource-independent and undeniable, and Authorise grants it only to IsPlatformAdmin (service.go:1171-1172), which is platform:manage in 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.

Counts are operations in openapi.json; platform:manage is the only scope that can refuse a Settings-eligible caller.

SurfaceopsGET / mutatingscopes presentverdict
People (users)125 / 7none at routerCALLABLE: authz is service-layer tenant:manage; one licence refusal on grant
Tenants42 / 22× platform:manageREAD CALLABLE, writes platform-only
Identity & SSO43 / 1noneCALLABLE (reads): 3 are self-authenticating; the 4th is a live probe
Domains & certificates137 / 66× platform:manageREAD CALLABLE, every write platform-only
Provider connections4513 / 3219× platform:manage, 2× tenant:manage, 2× tenant:readMIXED: vault/provider reachable, storage writes platform-only
Environment precedence62 / 42× platform:manage, 1× stack:manageREAD CALLABLE, config.set/unset platform-only
Backup policy4913 / 3612× stack:manage, 11× tenant:manage, 10× stack:operate, 9× stack:read, 7× platform:manageLARGELY CALLABLE: only the 7 key/mount routes refuse
Licence & entitlements71 / 6none at routerPLATFORM-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:67
if 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.

  • - 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.gate actually returns for a real Keycloak-authenticated console session on a live estate, specifically whether a tenant-realm console user resolves verb: "manage" and settings: true, and whether any real operator identity is a master-realm identity (and therefore silently platform-admin). applyMasterRealmPrivilege carries 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 from useConsoleGate.ts that ce had closed two days earlier, in af0502a4 (2026-08-18), and the stale text was later cited as corroboration for a fresh P0 report of the same closed hole. shc.backup.create is stack:operate; shc.backup.restore and DELETE /api/resource/Backup/{id} are stack:manage; the vault value reads and shc.vault.export are tenant:manage (ce 18abd9b9). Verified on the bitspur estate against daemon 0.0.62-SNAPSHOT-b02728a26 / ce 181d69fd6062: a corp-realm identity holding exactly tenant:read is refused X403900NOPERM on every one of those verbs, and the same identity raised to tenant:manage is served. Pinned in tests/_ce/modules/backup/router_permission_gate_test.go, router_tenant_read_refusal_test.go and tests/_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.

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 a ConfirmDialog, with describeError surfacing 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 / Paragraph from @multiplatform.one/components; SettingRow in SettingsScreen.tsx:34 is the label/value row.
  • Auth-off: AuthDisabledNotice for 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.”

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.

  • 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; then UserGrant, 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 X403988RBCEEO on 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.
  • 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, LicenseRefresh only 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 (both POST, unscoped at router); StackConfigNoref. Writes (ConfigSet / ConfigUnset) are platform:manage and 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.
  • 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 are platform:manage.
  • Read-only? Yes, and it should stay that way. DnsTakeover, DnsReap, CertsRotate are 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.
  • 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 by tenant: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 StackDetailScreen already 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:manage and include volume.rebind, restore-snapshot, volume.rm and assert-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.
  • 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.

  1. Does a real tenant-realm console session resolve verb: "manage" / settings: true from shc.console.gate? Needs a live estate probe.
  2. 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.
  3. 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.
  4. 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.