generated from coulomb/repo-seed
76 lines
3.0 KiB
Markdown
76 lines
3.0 KiB
Markdown
# 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
|
|
|
|
1. Repo files remain authoritative. A collaborator can change workplans only in
|
|
repos where Gitea allows them to push.
|
|
2. State Hub indexes files and records progress events, but it should not become
|
|
the primary identity authority.
|
|
3. Direct dashboard/API access is private by default. Do not publish State Hub
|
|
unauthenticated on the public internet.
|
|
4. 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`, or `observer`
|
|
- enforce domain write scopes in mutating endpoints
|
|
- keep repo permissions as the durable source of contribution authority
|
|
|
|
Candidate scopes:
|
|
|
|
```text
|
|
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.
|