Add role-based user administration phase

docs/roadmap.md

@@ -38,11 +38,12 @@ These constraints apply across all phases:
 | 5B | Offline xterm.js WebSocket serial terminal | **Complete** |
 | 6 | Authenticated SSH serial transport | **Complete** |
 | 7 | Local display and button interface | **In progress (7E validation)** |
-| 8 | Security and production hardening | **Planned** |
+| 8 | Role-based users and administrative access | **Planned** |
-| 9 | Authenticated, rollback-capable OTA | **Planned** |
+| 9 | Security and production hardening | **Planned** |
-| 10 | BLE serial transport and provisioning evaluation | **Planned** |
+| 10 | Authenticated, rollback-capable OTA | **Planned** |
-| 11 | Advanced network integration | **Under evaluation** |
+| 11 | BLE serial transport and provisioning evaluation | **Planned** |
-| 12 | Optional filesystem-backed features | **Under evaluation** |
+| 12 | Advanced network integration | **Under evaluation** |
+| 13 | Optional filesystem-backed features | **Under evaluation** |
 
 ## Completed foundation
 
@@ -237,7 +238,34 @@ The persistent yellow strip uses fixed-position serial, Wi-Fi-strength, USB, Web
 
 Completion requires electrical validation on the selected module, correct operation with all current transports, bounded display/button failure behavior, safe action confirmation, no unexplained serial or broker loss, and documented UART0 recovery.
 
-### Phase 8 — Security and production hardening
+### Phase 8 — Role-based users and administrative access
+
+Replace the single shared network credential with a bounded, persistent user system. Accounts have one of two authorization roles: `user` receives the currently implemented authenticated serial/status experience, while `admin` additionally receives administrative command and user-management capabilities. UART0 remains the physical recovery and bootstrap authority.
+
+Implementation sequence:
+
+1. **Phase 8A — User database and UART0 administration — Planned**
+   - Add a versioned, fixed-capacity user database with at most eight accounts, unique lowercase usernames, `user`/`admin` roles, per-account generations, and an invariant that prevents deletion or demotion of the final administrator.
+   - Store salted password verifiers rather than recoverable passwords. Support bounded hidden password entry and one-time generated passwords through UART0 commands for add/delete, role changes, password changes, and account inspection.
+   - Permit up to three SSH public keys per account. UART0 imports bounded OpenSSH public-key lines and lists fingerprints without exposing password verifiers or raw secret material.
+   - Migrate the existing shared credential transactionally so network recovery is preserved across power loss; document that append-oriented unencrypted NVS cannot guarantee physical erasure of historical plaintext entries.
+2. **Phase 8B — Role-aware HTTPS and SSH authentication — Planned**
+   - Authenticate HTTPS and SSH passwords through the common user database and retain a secret-free principal containing account ID, role, authentication method, and credential generation.
+   - Add SSH public-key authentication while retaining password authentication. wolfSSH authorizes the stored username/key pair and remains responsible for cryptographic signature verification; unsigned key probes never count as completed authentication.
+   - Bind WebSocket tickets and active SSH/WebSocket sessions to account generations so password, role, key, disable, or delete operations can revoke only the affected account.
+   - Preserve the current serial terminal, status, writer/observer behavior, and hidden administrative controls for normal `user` accounts.
+3. **Phase 8C — SSH administrative shell — Planned**
+   - Route authenticated `admin` SSH shell sessions to the same registered administrative command set as UART0, without creating a broker client. Normal users continue to receive the existing broker-backed serial stream.
+   - Serialize command parsing safely because ESP-IDF console internals are process-global. Use bounded per-session input/output queues and a separate command worker; only the SSH owner task may call wolfSSH APIs.
+   - Keep SFTP, SCP, `exec`, forwarding, subsystems, and unauthenticated shells disabled.
+4. **Phase 8D — Web user administration — Planned**
+   - Add an admin-only user-management interface and typed, bounded APIs for account CRUD, roles, password generation/change, SSH-key management, and revocation. Never expose a generic HTTP endpoint that executes arbitrary CLI text.
+   - Hide administrative navigation and controls for normal users, and enforce every authorization decision server-side so hidden UI is not treated as a security boundary.
+   - Preserve the existing normal terminal interface. Use strict origin/CSRF protections for mutations, secret-safe JSON encoding, one-time display of generated passwords, and no-store responses for administrative material.
+
+Completion requires migration and power-loss recovery tests, final-admin protection, malformed credential/key rejection, password and key login for both roles, targeted session revocation, concurrent normal/admin SSH operation, hidden and server-rejected user-level web administration, and continued UART0 recovery.
+
+### Phase 9 — Security and production hardening
 
 Harden stored credentials, boot integrity, update trust, failure diagnostics, and dependency maintenance. This phase must be staged carefully because some ESP32 eFuse operations are irreversible.
 
@@ -257,7 +285,7 @@ Planned work:
 
 Security features must be validated first on expendable hardware before any irreversible production configuration is recommended.
 
-### Phase 9 — Authenticated OTA and rollback
+### Phase 10 — Authenticated OTA and rollback
 
 Use the existing dual 4 MiB application slots and `otadata` partition to add safe firmware updates.
 
@@ -275,7 +303,7 @@ Planned work:
 
 OTA is complete only after successful update, interrupted-update, invalid-image, rollback, and configuration-persistence tests on hardware.
 
-### Phase 10 — BLE
+### Phase 11 — BLE
 
 Evaluate and, if resource limits permit, add BLE as another bounded transport or provisioning path.
 
@@ -292,7 +320,7 @@ Planned work:
 
 BLE remains subordinate to stable Wi-Fi and serial operation; it should be omitted if coexistence or memory costs cannot be bounded acceptably.
 
-### Phase 11 — Advanced network integration
+### Phase 12 — Advanced network integration
 
 These features are candidates, not current commitments:
 
@@ -303,7 +331,7 @@ These features are candidates, not current commitments:
 
 The device is not intended to become a general-purpose router. Captive-portal interception, unauthenticated DNS redirection, NAPT, and a plaintext serial listener remain out of scope unless the project requirements are explicitly revised.
 
-### Phase 12 — Optional filesystem-backed features
+### Phase 13 — Optional filesystem-backed features
 
 The `storage` partition is reserved but not currently mounted. Possible uses must be justified individually:
 
@@ -338,7 +366,7 @@ The following are not implemented merely because flash partitions or library sup
 - OTA download, image confirmation, or rollback policy.
 - Core-dump collection or secret-safe core-dump processing.
 - Filesystem mounting.
-- Public-key SSH user authentication.
+
 - SFTP, SCP, SSH `exec`, forwarding, or subsystems.
 - General routing, NAPT, captive-portal interception, or unauthenticated serial access.