3.0 KiB
State Hub Multi-User Access Model
State Hub is local-first coordination infrastructure. It reflects repo-backed workplans, progress, and operational state; it is not the authority for source control, host access, identity, or runtime secret custody.
Decision
For the current phase, enforce user access through the systems that already own the boundary:
- Gitea controls repository read/write rights.
- SSH authorized keys control host access.
- ops-bridge controls whether a remote machine can reach local services.
- OpenBao controls runtime secret custody after bootstrap.
State Hub API authentication is deferred until there is an active external collaborator or an exposed deployment that needs per-user write enforcement. Until then, State Hub stays private to local or tunneled operator networks.
Roles
| Role | State Hub access | Source of authority |
|---|---|---|
| Primary operator | Full read/write across domains | host access, repo ownership, operator secret custody |
| Domain collaborator | Read all public coordination state; write through owned domain repo and approved hub actions | Gitea repo permissions plus SSH/tunnel authorization |
| Observer | Read-only brief/dashboard access where explicitly exposed | tunnel or future API token |
Current Enforcement Boundary
- Repo files remain authoritative. A collaborator can change workplans only in repos where Gitea allows them to push.
- State Hub indexes files and records progress events, but it should not become the primary identity authority.
- Direct dashboard/API access is private by default. Do not publish State Hub unauthenticated on the public internet.
- Runtime secrets, service account keys, database credentials, and package tokens should move into OpenBao after the OpenBao bootstrap, unseal, audit, and recovery procedure is complete.
Future API Auth Trigger
Add API-layer auth when one of these becomes true:
- a second human needs direct State Hub API/dashboard mutation rights
- State Hub is exposed beyond localhost or a tightly controlled SSH tunnel
- automation needs per-consumer attribution and revocation independent of repo commits
- domain-scoped write checks are needed at request time
Future Token Shape
When the trigger is reached, implement a small token model rather than a full identity provider inside State Hub:
- accept NetKingdom IAM Profile OIDC tokens when the identity plane is ready
- support one emergency local admin token for break-glass operation
- map claims to
primary_operator,domain_collaborator, orobserver - enforce domain write scopes in mutating endpoints
- keep repo permissions as the durable source of contribution authority
Candidate scopes:
statehub:read
statehub:write
statehub:domain:<slug>:write
statehub:admin
Operator Rule
Do not store collaborator credentials in the State Hub database. Store secrets in OpenBao or the approved bootstrap bundle, and store source permissions in Gitea.