# 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.
