Fixed and improved token tracking

docs/multi-user-access-model.md

@@ -0,0 +1,75 @@
+# 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.